It is essential to document a code, so you need to ask yourself who it is aimed at. If necessary, produce several sets of documentation:
- for its author(s) to ensure that developments over time are properly understood,
- for its users, possibly several according to beginner or advanced level,
- for potential contributors.
You can also have “decision-maker” documentation which, without going into the details of how to use the software, provides a good, concise explanation of what the code is useful for.
In line with good development practice, the following documents should be linked to the code files:
- README: the entry point for the code. This file is automatically displayed when software forges are used. It provides an overview of all the relevant information relating to the software.
- LICENSE : software license.
- Eventually, the CONTRIBUTING (explaining how to contribute to the code), CHANGELOG (to describe major changes) and CITATION (to explain how to cite the code in a publication) files.
It should be noted that GitLab makes it very easy to integrate these files into your project, using pre-filled templates. In addition to these generic files, documentation generation tools allow you to access technical documentation elements from the code itself.
Here are a few examples of tools that are widely used:
It should also be noted that, when using a gitlab forge, it is possible to use the gitlab-pages mechanism to generate web pages that can format the code documentation.
You can find out more here.
The gitlab forges also include a wiki module that can be used to organise code documentation.