Aller au contenu

Maintenir la documentation

Comment la documentation suit le code sans relecture à la main.

Voir en Markdown

La documentation a une seule source : ce site. L’application ne recopie aucune page. Elle sait seulement quel écran renvoie à quelle page.

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.

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.

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.

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.