Documentation

Having documentation within code and about the code is crucial for developers to remember what different parts of the codebase do and how to create an effective development environment for the code to run. Documentation enables other developers and users to understand, contribute to, and deploy the project.

Readme
The first impression of your project will likely be given by a README file in your repository. In addition to extensive information available online about writing effective README files, essential elements that should be included are a brief description of the project's functionality and the context in which to use it, getting started instructions, licence information, and guidelines for contributing and citing the software.

Installation, dev and application documentation
A crucial aspect of documentation involves providing the installation process for software, outlining its dependencies, explaining its functionality, offering development information, and supplying tutorials and getting started instructions for users. Thorough documentation of this kind can be presented as a static website generated automatically. Some tools for achieving this include, but are not limited to, Sphinx and MkDocs. This type of website can also display code documentation, including details about functions such as their expected parameters and types, capabilities, and returned values. Diagrams illustrating the relationships between classes and methods can also be helpful. For further information, feel free to explore Doxygen. Other helpful additional tools for documentation include FORD for Fortran developers, pandoc for converting between various document formats, and Read the Docs.

For a seminar on 'Docs as code: How to write documentation with developers', go to the HiRSE YouTube Channel.

What the FZJ Software Guidelines say about Documentation

Class 1 and higher
A short, meaningful description of the purpose of the software must be included (e.g. in the form of a README file in the repository). New contributors should be able to participate in the development of the software.

Example: Explanation of the scientific context of the software, reference to publications and parties involved as well as technical information on use and further development. This makes access easier for new contributors in particular.

Class 2 and higher
Appropriate installation, development, and application documentation is provided for distributing and using the software. The documentation should be easily understood by others to facilitate contributions from other contributors.