Une documentation vieillit dès qu’elle vit séparée du code. C’est pourquoi, dans mes projets, elle se trouve dans le dépôt, structurée selon les phases de DSDM — du pré-projet au post-projet.
Dans le même commit
Qui modifie une fonction met à jour la documentation dans le même commit : exigence, procès-verbal de la timebox, mode d’emploi. Une vérification avant le commit rappelle de régénérer la version PDF.
Des décisions datées et motivées
Chaque décision figure dans un catalogue : question, variantes, recommandation, réponse, date. Dans deux ans, on sait encore pourquoi une chose est ainsi — et si la raison vaut toujours.
Un ton pour les humains
La documentation parle la langue de ses lecteurs : orthographe suisse, phrases courtes, termes techniques expliqués. Les diagrammes sont générés par un script pour suivre le texte.
Cela coûte un peu de temps à chaque timebox. Cela en fait gagner le double quand quelqu’un de nouveau rejoint le projet — ou quand j’y reviens moi-même après un an.