Une Documentation Technique Réellement Lue

La documentation technique échoue d’une manière précise et prévisible. Quelqu’un en écrit beaucoup pendant deux semaines calmes, le système change, personne ne la met à jour, et en moins d’un an elle affirme avec aplomb des choses fausses. À ce stade, elle vaut moins que rien, parce que le lecteur qui lui fait confiance agit sur des informations qui ne tiennent plus.

La réaction habituelle consiste à en écrire davantage, ce qui ne fait qu’accélérer le même échec. La réaction utile consiste à en écrire moins et à choisir quoi, parce que la contrainte n’est pas l’effort de rédaction. C’est la maintenance.

Le seul test durable pour savoir si un document doit exister : quelqu’un s’en apercevra-t-il le jour où il deviendra faux ? Un guide de déploiement sert souvent, et ses erreurs remontent donc immédiatement. Une description de vingt pages d’un sous-système est lue une fois, et ses erreurs remontent dix-huit mois plus tard, quand quelqu’un agit dessus. Les documents que personne n’exerce pourrissent en silence, et ce sont ceux-là qu’il faut laisser non écrits.

Pourquoi elle se périme

Trois mécanismes, et un seul relève de la paresse.

La documentation vit loin de ce qu’elle décrit. Modifier le code n’est pas modifier une page de wiki, donc leur alignement dépend de la mémoire de quelqu’un. Cette mémoire fait défaut, de façon fiable, et plus le document est éloigné du code, plus la dérive est rapide.

Elle décrit l’implémentation plutôt que l’intention. Un document qui explique comment un composant fonctionne aujourd’hui est invalidé par chaque refactorisation. Celui qui explique pourquoi le composant existe et quelle contrainte il satisfait survit, parce que la raison change bien moins souvent que le code.

Personne n’en est propriétaire. Une documentation qui appartient à tout le monde n’appartient à personne, et il n’existe aucun moment où son exactitude devient le problème de quelqu’un en particulier.

Les remèdes découlent des causes : la garder près du code, écrire l’intention plutôt que le mécanisme, et donner à chaque document un responsable nommé ainsi qu’une occasion réelle de servir.

La documentation technique qui mérite d’être maintenue

Quatre documents couvrent l’essentiel de la valeur. Tout le reste doit se justifier.

Un README qui vous met en route. Ce qu’est ce projet, comment l’installer, comment lancer les tests, comment déployer. Il sert en permanence, donc ses erreurs remontent vite. C’est le document au meilleur rendement de n’importe quel dépôt, et aussi celui qu’on laisse le plus souvent tel quel, un modèle de projet que personne n’a édité.

Un aperçu d’architecture. Quelles sont les grandes pièces, comment elles communiquent et pourquoi elles sont séparées. Une page et un schéma, qui décrivent la forme plutôt que le détail. Il change rarement et répond à la question que chaque nouvel arrivant reconstitue sinon en lisant tout.

Les fiches de décision. De courtes notes qui consignent une décision, les options écartées et la raison du choix. Le métier les appelle le plus souvent des Architecture Decision Records, ou ADR. On les ajoute sans jamais les mettre à jour, et elles évitent la forme la plus coûteuse de travail refait : rejouer mal un débat déjà tranché parce que plus personne ne se souvient de la contrainte qui l’avait tranché.

Des runbooks pour ce qui casse. Un runbook est la procédure d’intervention : comment diagnostiquer et corriger les pannes que vous avez réellement connues. Il s’écrit juste après un incident, tant qu’il est frais, et il s’éprouve au suivant. Un runbook que personne n’a jamais suivi est un brouillon.

Aucun de ces quatre documents ne décrit le fonctionnement du code. C’est le rôle du code, et toute prose qui le double devient une seconde source de vérité qui finira par contredire la première.

Écrire pour quelqu’un de fatigué et pressé

La plupart des documentations techniques sont lues sous pression, par une personne qui a une question précise, souvent en dehors des heures de bureau. Écrivez pour ce lecteur, pas pour celui qui aurait le temps.

Répondez d’abord, expliquez ensuite. La personne qui lit votre runbook à deux heures du matin a besoin de la commande, puis du raisonnement. Le contexte avant la réponse est une structure qui convient à l’auteur et à personne d’autre.

Soyez concret. De vraies commandes, de vrais chemins, de vraies valeurs d’exemple. « Configurez les variables d’environnement appropriées » n’est pas une instruction, c’est la description d’une instruction.

Dites ce qui va mal tourner. Les modes de défaillance et l’allure qu’ils prennent sont souvent le contenu le plus utile, parce que c’est précisément ce que le lecteur est en train de vivre.

Faites assez court pour que cela reste vrai. Chaque phrase est une dette de maintenance. Une page qui couvre le cas courant et reconnaît ses propres limites vaut mieux qu’un document qui couvre tout et se trompe à trois endroits.

La discipline qui rend une page citable par un système de récupération la rend aussi utilisable par un collègue épuisé, ce qui rejoint exactement ce que dit, à propos des textes publics, notre guide sur pourquoi votre contenu se classe mais n’est jamais cité.

La maintenir en vie

Mettez-la dans le dépôt. Un document qui voyage avec le code est modifié dans la même revue que le code, et c’est le seul mécanisme qui maintient les deux alignés de façon fiable.

Relisez-la en revue de code. Si un changement rend un document faux, cela devient un commentaire de revue comme un autre. C’est l’habitude au meilleur effet de levier disponible, et elle ne coûte rien.

Testez ce qui est testable. Des instructions d’installation qui s’exécutent dans une chaîne d’intégration cessent d’être un vœu pieux. Si votre README affirme que trois commandes suffisent à obtenir un système qui tourne, faites-le prouver par un job.

Supprimez sans état d’âme. Un document faux est pire qu’un document absent, parce qu’on lui fait confiance. Quand quelque chose se périme et que personne ne le corrigera, retirez-le et notez ce qui a été perdu.

Datez ce qui expire. Tout ce qui contient un numéro de version, un prix ou une dépendance externe doit porter une date, pour que le lecteur juge lui-même s’il peut s’y fier.

À quoi cela sert vraiment

La documentation est le mécanisme par lequel le savoir cesse de dépendre des individus. C’est tout le bénéfice, et c’est pourquoi l’argument en faveur de sa rédaction est économique et non esthétique.

Un système qu’une seule personne sait déployer a un délai de reprise égal à la disponibilité de cette personne. Un composant que personne ne sait justifier finit reconstruit ou conservé par superstition. Les deux apparaissent comme constats en due diligence technique, les deux allongent l’intégration des développeurs, et les deux sont le même problème sous des habits différents.

Mecanik rédige ces documents dans le cadre de la passation, sur chaque mission, au titre de notre travail de développement logiciel. Le document qui finit par servir est presque toujours plus court que celui qui avait été demandé.

Questions fréquentes

Pourquoi la documentation technique se périme-t-elle ? Parce qu’elle vit loin du code, donc l’alignement dépend de la mémoire de quelqu’un ; parce qu’elle décrit l’implémentation plutôt que l’intention, donc chaque refactorisation l’invalide ; et parce que personne n’en est propriétaire, donc son exactitude n’est jamais le problème précis de qui que ce soit. La garder dans le dépôt et la relire en même temps que les changements de code traite les trois causes d’un coup.

Quelle documentation une équipe logicielle doit-elle maintenir ? Quatre choses couvrent l’essentiel de la valeur : un README qui met le système en route, un aperçu d’architecture d’une page expliquant la forme et le raisonnement, des fiches de décision en ajout seul qui consignent pourquoi les choix ont été faits, et des runbooks pour les pannes que vous avez réellement connues. Les descriptions du fonctionnement du code ne figurent pas sur la liste.

Qu’est-ce qu’une fiche de décision ? Une note courte qui consigne une décision, les options envisagées et la raison du choix. Comme elle enregistre un moment plutôt qu’un état courant, elle n’a jamais besoin d’être mise à jour, et elle évite que des questions tranchées soient rejouées mal par des gens qui ne se souviennent plus de la contrainte qui les avait tranchées.

Comment faut-il rédiger la documentation technique ? Pour quelqu’un de fatigué, sous pression, qui cherche une seule chose précise. Répondez d’abord et expliquez ensuite, utilisez de vraies commandes et de vrais chemins plutôt que leur description, dites ce qui va mal tourner et à quoi cela ressemble, et faites assez court pour que cela reste vrai.

Faut-il supprimer une documentation périmée ? Oui, si personne ne la corrigera. Un document faux est pire qu’un document absent, parce que le lecteur lui fait confiance et agit dessus. Supprimez-le et notez ce qui a été perdu, et datez tout ce qui contient un numéro de version, un prix ou une dépendance externe pour que les lecteurs jugent par eux-mêmes.