Several aspects of documentation are related to the life-cycle of our products. As a very basic foundation, it is mandatory to have a kind of an in-place documentation, for example by appropriate verbose function documentation.
A good documentation SHOULD focus on several target groups (when applicable): developer, operator and user of the software.
Also it is RECOMMENDED to create and update a general overview of the software architecure accompanied by at least one
graphical representation of the major components and their interaction.
### Docs-as-code
A documentation should be placed within the software repository. Furthermore for the documentation writing, building, testing and publication process, all quality criteria, workflows and pipelines SHOULD be set up alike those for the software itself. In this way documentation is treated the same as code including the usage of version control, issue tracker, code reviews and automated tests.
A presentation of the usage of this approach for a long-term scientific software project is available at [zenodo](https://zenodo.org/records/7260347). In general, this approach can be applied to small-scale projects as well.
Docs-as-code is not an out-of-the-box environment for creating neat documentations. It is up to the project to decide for a markup format and a static site generator.
