Timely Solution Documentation

Welcome to Timely's solution documentation site. This site builds out comprehensive code documentation based on the C# classes and XML documentation within code files, using the DocFX tool. DocFX is essentially a static site generator with an inbuilt templating engine that crawls .Net project files for XML comment syntax and markdown files.

Using this project

There are two key parts to configuring and compiling the resulting documentation site:

  • docfx.json for config
  • docfx.exe for build and serve

Getting started

To use this project, you need to have the DocFX tool installed. Run the following command to get this installed on your local machine: dotnet tool update -g docfx

Once that's successful, you should be able to run docfx --serve from within the root of this project (i.e. whichever folder contains the docfx.json file). The site should build out its pages and serve the site at http://localhost:8080.

Configuration

The site is generated based on the settings defined in the docfx.json file. You can read a detailed treatment of this file on the main DocFX site.

You will see there is also a Powershell script: unflatten.ps1. This script is a polyfill in lieu of native support for nested contents pages on the generated documentation site. The script takes a single argument: the relative location of the API contents yml file. If running the script from the root of the site, the command would look as follows:

.\unflatten.ps1 api\toc.yml

The script will then reconfigure the api/toc.yml file to indent all entries relative to their parents.

Writing code documentation

C# documentation should be brief enough that it can be quickly understood by the reader, but offer enough context around the purpose of the class or method (the "why") that the reader can infer intent and understand where the connections or information flows should lead.

The Microsoft Recommended XML Tags documentation offers excellent descriptions of the available tags and their usage and purpose. It likely won't always be necessary to include everything, but maintainers will have a better experience working in the code with more comprehensive use of the correct tags and their syntax.