Documentation¶

Documentation is a crucial part of every project, thus the following guidelines apply to documentations:

Ensure you’ve documented the project
High-level documentations are often preferred over low-level «techie docs»
Think about your target audience / stakeholder before you start documenting
Check out our other documentations for examples
Leverage Emoji’s (and Emoji Finder) in configuration files and alike

Language¶

As mentioned in Communication, our documentation language is English.

Markdown¶

For most projects, the documentation is written in basic Markdown syntax files.

For GitLab projects, the entrypoint for the documentation is usually the README.md, stored in the root of the Git project / repository.

Hint

GitLab improved, resp. enhanced the basic Markdown syntax with their GitLab Flavored Markdown version.

Documentation files¶

By convention, every project provides the following documentation files, one per audience:

File	Audience	Content
`README.md`	Everyone	What the project is, why we have it, and where it’s deployed
`docs/USAGE.md`	Users	How to use the project, e.g. access, daily tasks, tips & FAQs
`docs/MAINTENANCE.md`	IT admins	How to configure, update, and test the project
`docs/TROUBLESHOOTING.md`	IT admins	How to debug the project, and how to fix known problems

Hint

The README.md is the entrypoint, stored in the root of the project, and links to the files in the docs/ directory. Additional, more detailed docs can be stored in the docs/ directory as well, and should be linked from one of the files above.

Note

If a project already provides its docs in the docs/ directory (e.g. Sphinx docs), the usage, maintenance & troubleshooting are integrated as chapters of those docs instead (e.g. docs/usage.rst). The README.md stays in the root of the project and links to them.

Sphinx¶

Most likely, more complex documentation will be based on Sphinx, and reside in the docs/ directory.

To build the docs locally, have a look at the make Documentation targets. To build the docs during the CI pipeline, have a look at the docs GitLab CI file.

Get started with Sphinx¶

Here are some good resources to get started with Sphinx:

Hint

Feel free to have a look at the source code of this documentation by either browsing the GitLab project, or by using the Edit this page link in the header.

Sphinx theme¶

We’re using our own Sphinx extension (confirm-sphinx), which provides a theme matching the 🎨 Corporate design. It also applies common defaults, so we don’t have to repeat ourselves in every project.

Intersphinx¶

One big advantage of Sphinx is an extension called Intersphinx, which can generate automatic links to the documentation of objects in other projects.

Hint

To see all links of an Intersphinx mapping file, you can use the following command:

python3 -msphinx.ext.intersphinx {URL to .inv file}

Mermaid in Sphinx¶

When you’re looking to include diagrams in your docs, have a look at the Mermaid chapter. Mermaid diagrams are supported out of the box by our Sphinx theme, see the enabled extensions.

PlantUML in Sphinx¶

When you’re looking to include diagrams in your docs, have a look at the PlantUML chapter. There’s a Sphinx PlantUML Plugin, which can be installed & configured to leverage the plantuml-client:

extensions = [
    # …
    'sphinxcontrib.plantuml',
    # …
]

plantuml = 'plantuml-client'