De la documentation que les gens lisent vraiment
Quatre documents qui suffisent
Un fichier de démarrage. Ce que c'est, comment l'exécuter en local, comment lancer les tests et qui demander. Il doit être précis — c'est le document vérifié à chaque intégration.
Des décisions d'architecture. Une page par décision significative : contexte, options, ce qui a été choisi et pourquoi. Court et daté.
Les opérations. Quoi faire quand quelque chose se casse, comment déployer, comment revenir en arrière.
L'interface. Depuis le code lui-même, pour qu'elle ne vieillisse pas.
Comment la garder fraîche
De la documentation qui vit près du code et est mise à jour dans la même demande de fusion. Un document ailleurs vieillit en deux mois, et pire — reste d'apparence faisant autorité.
Quoi ne pas documenter
Ce que le code dit clairement. Un commentaire qui décrit une ligne est superflu ; un commentaire qui explique pourquoi une approche inhabituelle a été choisie vaut de l'or.
Pour aller plus loin
Vérifiez le fichier de démarrage à chaque intégration : faites-le suivre à la lettre par un nouvel arrivant et notez chaque endroit où il a bloqué. C'est la seule façon de trouver les hypothèses silencieuses que tous les vétérans gardent en tête et que personne n'a écrites.