Comment avoir un manuel à jour ?

Quel que soit le projet (comme Win32Service), il est y a toujours une documentation. Par exemple, le manuel d'installation, le mode d'emploi pour l'utilisateur final ou la documentation pour les développeurs.

Malgré ma grande affection pour une documentation bien écrite et utile (comme par exemple La double authentification en Symfony). Je suis obligé de constater que bien souvent elle n'est pas à jour. Même la documentation de Symfony ou de Sylius a des coquilles ou parfois des pans entiers qui ne sont plus à jour.

Les projets communautaires

Pour de gros projets tels que Symfony ou Sylius, ce n'est pas la même équipe qui écrit le code et la documentation. Comme à chaque fois quant il y a deux équipes distinctes, la communication est plus difficile ce qui provoquer ces décalages entre le code et la documentation.

Tel que Rust, il est possible d'ajouter la documentation technique avec le code pour l'extraire avec un outil. Ce sont des choses qui ont existé en PHP (Symfony 1 avait une tel documentation) mais force est de constater qu'il est compliqué pour les développeurs d'écrire des documentations.

La doc utile

Mais outre la documentation pour les autres — dont ont doute souvent de l'utilité, il y a la documentation pour soi.

Saurons-nous demain ce que nous avons fait sur un projet il y a 6 mois. Et pour cela il est nécessaire de documenter le code et le projet.

Comment installer le projet ? Que fait ce code complexe — dont Sonar nous indique la nécessité de réduire la complexité ? etc.

Nous avons besoin de documentation pour nous, mais là aussi comment faire en sorte qu'elle reste à jour ?

Ma technique

Voici ma façon de faire, vous pouvez vous en inspirer et me partager votre façon de faire dans les commentaires.

Il y a toujours qu'un seul point d'entrée dans la documentation. En général c'est le fichier README.md présent à la racine du projet.

Commençons par la doc d'installation. À chaque fois que j'ajoute ou modifie un élément qui change la façon d'installer le projet, je mets à jour la documentation. De plus je fais en sorte qu'une erreur arrive si tout n'est pas correct.

Pour compléter la documentation, la configuration par défaut est la configuration de développement (oui mon .env contient des "secrets" de dev tel que le mot de passe de la base de données, mais pas les clés de service tiers).

Validation ultime, je prévois d'installer le projet dans une VM pour valider la procédure d'installation du projet. De la même manière que les équipes d’infrastructure testent les procédures de restauration des données.

Passons maintenant à la documentation technique, en général, elle est dans le code. Pour certaines choses elle est dans le README du projet. Mais si la quantité de documentation est importante, je la déplace dans un dossier "doc".

Pour savoir si elle est toujours à jour, je me mets dans un mode "nouveau sur le projet" et je tente de comprendre ce que dit la doc.

L'exercice n'est pas évident. Il est nécessaire de ne pas aller trop loin en se plaçant comme un junior qui sort de l'école. Ni comme un senior qui a tout vu et qui comprend juste en lisant la seule ligne de commande présente dans la doc...

Conclusion

Malgré tout, les documentations ne sont pas toujours fidèles à la réalité. C'est pour cela que je préfère lire le code lorsque cela est possible. Le code ne ment pas, soit il fonctionne soit il ne fonctionne pas...

Cependant le manque de documentation est extrêmement frustrant pour les librairies et projet libre ou Open Source. Généralement, je considère ce genre de projet comme de faux projet et je passe mon chemin comme beaucoup et c'est normal.

Merci d'avoir lu jusqu'ici, et vous comment gérez-vous votre documentation ?

Jean-Baptiste Nahan

Consultant Expert Web, j'aide les entreprises ayant des difficultés avec leur projet Web (PHP, Symfony, Sylius).

@jbnahan69 | Macintoshplus | Linkedin | JB Dev Labs