La documentation d’un code est essentielle, il faut se demander à quel public on s’adresse et produire éventuellement plusieurs documentations :
- pour son/ses auteurs afin d’assurer la bonne compréhension des développements dans le temps,
- pour ses utilisateurs, éventuellement plusieurs selon le niveau,
- pour les contributeurs éventuels.
On peut aussi avoir une documentation «décideur» qui sans rentrer dans les détails d’utilisation du logiciel, explique suffisamment bien et de manière concise à quoi le code est utile.
En lien avec de bonnes pratiques de développement, il est recommandé d’associer aux fichiers du code les documents suivants :
- README : le point d’entrée sur le code. Ce fichier est automatiquement affiché lors de l’utilisation de forges logicielles. Il permet d’avoir une vue globale de toutes les informations pertinentes liées au logiciel.
- LICENSE : la licence du logiciel.
- Éventuellement, les fichiers CONTRIBUTING (expliquant comment contribuer au code), CHANGELOG (pour décrire les évolutions majeures) et CITATION (pour expliquer comment citer le code dans une publication).
Il est à noter que GitLab permet d’intégrer très facilement ces fichiers dans votre projet, à travers des modèles préremplis. Outre ces fichiers génériques, des outils de génération de documentation permettent, à partir du code lui-même, d’accéder à des éléments de documentation technique.
Quelques exemples d’outils qui sont très utilisés :
A noter aussi que, dans le cas de l’utilisation d’une forge gitlab, il est possible d’utiliser le mécanisme des gitlab-pages pour la génération de pages web pouvant mettre en forme la documentation du code.
Vous trouverez un peu d’informations sur ce sujet ici.
Les forges gitlab intègrent aussi une fonctionnalité de wiki qu’il est possible d’utiliser pour organiser la documentation du code.