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

A reference is what our RAT Documentr generates.