How#

How to write documentation#

Follow the Diataxis framework for documentation.

This involves separating your documentation in to 4 different sections based on separate aims for readers.

How to write a tutorial#

A tutorial should include step by step instructions with expected behaviours. This should not focus on any deeper explanation.

An analogy of this is teaching a young toddler to build a toy train track. They do not need to know the physics related to how the train will go through the track. They need only to see how to lay the track pieces.

How to write a how to guide#

A how to guide should provide a quick and to the point description of how to solve a specific problem.

An analogy of this would be a recipe. The recipe will not necessarily explain how to chop an onion and/or why we are chopping an onion it will tell you to chop an onion as a step of cooking a particular meal.

How to write an explanation section#

The explanation section should provide a deeper understanding of the concepts under the code.

An analogy of this again related to a recipe would be a book on the chemistry of taste and why a chopped onion adds a specific type of flavour to a meal.

How to write a reference section#

The reference section should provide an overview of the specific tools, commands and indeed place for background reading as well (although this can also be referred to in the explanation section).

How to include section headers in markdown#

To include a section header in markdown use #. The number of # corresponds to the level of the section header.

Tip

# Section

For example:

# The absorption library

Functionality to study the absorbing Markov chains.

## Tutorial

How to include code in markdown#

To include code in markdown use three ` marks followed by the name of the language:

Tip

```<language>

<code>
```

For example:

```python
import sympy as sym

x = sym.Symbol("x")
```

Would render as:

import sympy as sym

x = sym.Symbol("x")

It is also possible to include code in markdown using an indented block:

For example:

Here is some code:

    import sympy as sym

    x = sym.Symbol("x")

Would render as:

Here is some code:

import sympy as sym

x = sym.Symbol("x")

Attention

Using an indented block does not allow you to specify the language and can lead to mistake when combining with other nested statement.

How to include an image in markdown#

To include an image in markdown use ![]() language:

Tip

![caption](path)

For example:

Here is an image:

![An image](image.jpg)

Attention

If the image file is not located in the same directory as the markdown file the path to the file must be correct.