Que l’on soit nouveau dans une boîte, sur un projet existant, ou même, que l’on veuille implémenter une lib externe dans son projet on s’est tous déjà cassé les dents sur une documentation parfaite, enfin parfaitement pauvre, oubliée, foireuse et illisible …. Pourtant, ce n’est pas si compliqué d’en rédigé une …
Oui, on ne va pas se cacher, une documentation parfaite est utopique à peu près partout … Mais on peut se donner les moyens d’en pondre une moins mauvaise que les autres, juste avec ces 7 points.
Une documentation parfaite doit être :
Claire et agréable
Pour qu’elle soit lue, il faut avant tout que la doc soit lisible & agréable, sinon la personne qui voudra la lire, ne la lira pas ou à contrecoeur (donc ne retiendra pas les informations importantes).
Donc exit les interfaces des années 80 avec du gris partout et des couleurs vives par-ci par-là … Il faut une interface aérée qui permet la mise en valeur des éléments importants
Le texte, en lui-même, doit être agréable et compréhensible, il faut toujours partir du principe que la personne vient d’arriver et donc on évite les termes métier trop spécifiques, on mettra à la place des termes suffisamment générique pour être connu de tous, du moins dans les cas où c’est possible.
Dans le cas contraire, pense à inclure des références pour faciliter la recherche du lecteur
La différence entre une documentation agréable et celle d’un autre siècle …
Complète
Une documentation complète évite de perdre du temps, une exception, une erreur, un cas de figure non géré, cela doit être documenté.
Survolable
La doc parfaite permet de la survoler pour trouver ce que l’on cherche le plus vite possible, le nom des pages doit être précis et générique afin d’être compris au premier coup d’oeil
Le contenu de la page doit avoir suffisamment de découpage (titre / sous-titre) pour éviter un fichier trop gros & indigeste
Avec plein d’exemples !
Les exemples c’est la vie !
Une documentation avec des exemples permet de combler un manque de précision sur un sujet voire même l’absence d’explication, avec un exemple la personne à plus de change de comprendre comment utiliser le composant !
Cela ne veut pas dire que tu peux “oublier” de faire une partie de la doc, juste qu’en cas d’erreur de ta part, le lecteur ne sera pas (complètement) perdu
Quelque part …
Qui n’a jamais entendu le fameux “mais si c’est dans ce coin-là” alors qu’absolument pas … Une documentation efficace est avant tout une documentation que l’on peut trouver facilement …
Modifiable & à jour
Une doc à jour c’est comme une couverture de test unitaire suffisante …. ça arrive rarement.
“Je le ferai plus tard” / “pas le temps” et j’en passe, autant d’excuses car on n’a absolument pas envie de faire cette documentation ….
Moi le premier, je ne supporte pas faire de la doc.
Sauf que la doc doit être faite, donc quand tu prévois ton temps de développement, rajoute obligatoirement celui des tests unitaires et de la doc …
Le temps va quasiment doubler mais c’est nécessaire, malheureusement …
Dans le cas contraire, le temps perdu par les personnes qui passeront derrière toi, sera bien plus grand que celui que tu aurais “perdu” en faisant cette doc
Une documentation doit aussi être simple à faire évoluer …. Car d’autres que toi peuvent tomber sur le projet et le faire évoluer, et donc sa doc aussi
Par exemple Swagger permet de faire la doc dans son code via des annotations, ou en dehors via un éditeur simple et assez pratique / ergonomique …. Tout en ayant suffisamment de doc pour ne pas être perdu en faisant sa propre doc 😇
Répétitive
Si tu dois mettre les mêmes informations à plusieurs endroits, fait le !
Qui a envie de lire une documentation en entier ? Personne
Si c’est nécessaire de répéter la même chose à X endroit, répète le X fois …
Trouve ton outil qui te convient, et surtout VA FAIRE CETTE FOUTUE DOC que tu dois faire depuis 6 mois, ou plus….