For a successful project, the documentation is as important as testing the code. The intention of this section is to provide basic guidelines and tips to write good project documentation, for HSE (in this DocuWiki) and for our customers.

These better practices are mainly inspired by The Hitchhiker's Guide to Documentation!. For a more comprehensive guide about documenting software projects, take a look at it.

First of all, be clear about what you want to write. The type of the documentation heavily influences the structure and style. Usually we use three different types:

• Tutorial (aka “Quick Start” or “Getting Started”)
• Guide (more comprehensive)
• Reference (aka API documentation)

Tutorials are like a front door or a shop window. They demonstrate how your project “feels”.

New users usually first read the “Quick Start” section. They want a simple example to see how this library or application can be used. Give the user a quick lift.

See also https://docs-guide.readthedocs.io/en/latest/tutorials/

Should be a comprehensive documentation of the project. Main aspects are:

• show the vast majority of possible options (but should not show all possible options – that is the task for reference),
• show how all concepts fit together,
• answer the question “why?”.

References should answer the question “how?”. For this, it must include every detail. For example, an API reference documents every public function and every parameter. It can contain short code examples, too.

A reference is what our RAT Documentr generates.

Good advices for writing documentation can be found here: https://docs-guide.readthedocs.io/en/latest/writing/

To find and maintain a good structure is critical for good documentation. For this, Read The Docs provides us a good help, too: https://docs-guide.readthedocs.io/en/latest/structure/

For our DokuWiki we should maintain a set of templates. These tempates provide a common structure for each type of documentation and makes it easier to start (no “blank page” phenomena).

Last but not least, you can find helpful advice for a good writing style here: https://docs-guide.readthedocs.io/en/latest/style/