Documentation guidelines¶

This site is built by MkDocs and uses the Material for MkDocs theme with extensions.

You can serve documentation locally with the run docs serve local command.

Organization¶

The site structure is defined by the nav key in the mkdocs.yml file.

We strive to follow the principles of the Diátaxis documentation framework.

When adding new pages, first think about what it is exactly that you are trying to document. For example, if you intend to write about something everyone must follow as a standard practice it would be classified as a guideline whereas a short piece about performing a particular task would be a how-to.

After deciding the kind of content, strive to further segment the page under logical groupings for easier navigation.

Line continuations¶

For prose where the rendered content should have no line breaks, always keep the Markdown on the same line. This removes the need for any stylistic enforcement and allows for IDEs to intelligently wrap as usual.

Tip

When you wish to force a line continuation but stay within the block, indent by 2 spaces from the start of the text and end the block with a new line. For example, the following shows how you would achieve a multi-line ordered list item:

Markdown

1. first line

     second line

1. third line

Rendered
1. first line
  
  second line
2. third line

Emphasis¶

When you want to call something out, use admonitions (with the Blocks syntax) rather than making large chunks of text bold or italicized. The latter is okay for small spans within sentences.

Here's an example:

Markdown
```
/// info
Lorem ipsum ...
///
```
Rendered

Info

Lorem ipsum ...

Links¶

Always use inline links rather than reference links.

The only exception to that rule is links that many pages may need to reference. Such links may be added to this file that all pages are able to reference.

Abbreviations¶

Abbreviations like DSD may be added to this file which will make it so that a tooltip will be displayed on hover.