Maintenir la documentation
Comment la documentation suit le code sans relecture à la main.
La documentation a une seule source : ce site. L’application ne recopie aucune page. Elle sait seulement quel écran renvoie à quelle page.
Ce qui suit le code tout seul
Section intitulée « Ce qui suit le code tout seul »| Ce qui change dans le produit | Ce que le site fait |
|---|---|
| Un module est livré, retiré ou change de menu | La liste des modules livrés se relit dans le registre à chaque construction. Un contrôle refuse la publication si elle est périmée. |
| Une fonction ou un type de l’API change | La référence générée se refait à partir des commentaires du code, et un contrôle refuse la publication si elle est périmée. |
| Une règle de développement change | Les règles sont des données : la page, le kit pour un agent et l’export lisible par machine sortent de la même source. |
Ce qui s’écrit, et ce qui le vérifie
Section intitulée « Ce qui s’écrit, et ce qui le vérifie »Une page de la partie Utiliser dit, dans son en-tête, les écrans qu’elle explique (ecrans) et un résumé de trois ou quatre phrases (resume). Le site en tire un fichier, aide-par-ecran.json, que le produit reprend. Le « ? » d’un écran affiche le résumé et renvoie à la page.
Au commit, le produit compare ce fichier au menu : une entrée de menu sans aide est signalée. On ne documente donc pas par discipline, on documente parce que l’oubli se voit.
Qui rédige
Section intitulée « Qui rédige »La première version d’une page se confie à un moteur de rédaction, qui part du texte de l’écran et du code. Un humain la relit : la page est un engagement envers l’utilisateur. Ensuite, chaque changement d’écran touche sa page dans le même commit, et la mention « vérifié le » de la page change avec lui.
Ce qu’on n’écrit pas
Section intitulée « Ce qu’on n’écrit pas »Pas de vidéo : elle vieillit à chaque changement d’écran, et personne ne la relit. Pas de capture qui montre un vrai nom : les captures se prennent sur des données inventées.