Writing developer docs¶

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

You can serve documentation locally with the dda run docs serve 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, further segment the page under logical groupings for easier navigation.

Ordered lists¶

Each item in an ordered list should start with 1. and let rendering handle the rest. This is recommended for two reasons:

Changes to the list size do not require re-numbering unmodified items and therefore reduces the diff when reviewing.
Rendering will expose improper formatting by having the sequence broken rather than hiding such issues.

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 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.