Writing user manual content

Documentation that covers overall concepts and tasks belongs in the manual.

Manual content uses DocFX-flavored markdown (DFM), which is reasonably close to Github-flavored markdown, to which it adds a few features.

The markdown files for the Manual go in the Documentation~ folder at the root of each package directory. The table of contents is a bulleted list of links in the file TableOfContents.md, in the same folder.

Each package has a separate set of documentation. Linking between packages is currently problematic. Such links must be absolute html links to the published package docs on the web. The problematic aspect is that the published URLs contain a version number. You can change the version to reference @latest, but sometimes a specific version is necessary.

Manual code samples

For embedded code samples, place a line containing three backtick characters above and below the code. On the top line, add a space and "lang-cs" (or other programming language code) to provide a hint to the syntax highlighter.

\``` cs
for(as many lines as you need)
{
    var code = Goes.Here;
}
\```

You can just indent one or more lines of code by 4 spaces, but syntax highlighting can be inconsistent.

Automatically compiled code examples

Instead of typing code in the markdown file where it potentially can get outdated, you can write your example code in a C# file and reference it from the markdown file. The doc tools extract the code from the C# file and inserts it into the markdown when it generates the manual .html files.

To reference one or more lines of code, use the following markdown syntax (similar to image syntax):

[!code-lang[name](relative_path#region)]

Where:

  • lang is the language code. Use cs for C# code.
  • name is a string. I'm not really sure what it is used for.
  • relative_path is the relative path to the code file.
  • region is the region in the code file that indicates which lines to extract.

For example:

[!code-cs[speedjob](../DocCodeSamples.Tests/ChunkIterationJob.cs#speedjob)]

You should place the example code in the DocCodeSamples.Tests package. Currently one exists for the Entities package, but we can create more as needed. (Note a "../package/" element used to be required in the example path. This is no longer true and must be omitted.)