Une documentation de quatre-vingts pages n'est pas quatre fois plus utile qu'une de vingt. Elle est moins utile, parce qu'elle n'est pas lue, et parce qu'elle n'est plus mise à jour au bout de six mois.
La question qui définit ce qu'il faut écrire
Une seule : quelqu'un qui n'a jamais vu ce système et qui doit le réparer un dimanche, que doit il trouver ?
Cette personne n'a pas besoin de comprendre l'architecture. Elle a besoin de savoir où sont les accès, comment on redémarre, ce qui casse habituellement, et qui appeler.
Tout ce qui ne sert pas à cette personne là est de la documentation d'auteur, écrite pour montrer qu'on a bien travaillé, et personne ne la lira.
Les cinq pages qui suffisent
Elles se relisent en un quart d'heure et se mettent à jour en dix minutes, ce qui est la seule raison pour laquelle elles restent justes.
Les accès
Où est hébergé quoi, comment on entre, et où sont les identifiants, sans jamais les écrire dans le document. Cette page est la plus utile de toutes et elle manque presque toujours.
La remise en route
Les étapes pour redémarrer après un arrêt, dans l'ordre. Écrite en les faisant réellement, pas de mémoire, sinon il manque toujours une étape.
Ce qui casse habituellement
Les trois ou quatre pannes déjà vues, leur signe et leur correction. C'est la page qui fait gagner le plus de temps et elle s'écrit au fil de l'eau.
Les décisions et leur raison
Pourquoi telle solution a été retenue, et ce qui avait été écarté. Sans elle, un successeur refait le même détour, ou pire, défait une décision qui avait une bonne raison.
Qui appeler
Les personnes et les fournisseurs, avec leur périmètre. Une page qui vieillit vite et qu'il faut donc dater.
Une documentation qui exige plus de dix minutes pour être mise à jour ne sera pas mise à jour. C'est la contrainte qui décide de sa longueur, pas l'exhaustivité.
Ce qui se documente dans le code plutôt qu'à côté
Une partie de ce que l'on met dans un document appartient au code, où elle a une chance de rester juste.
Un nom de variable explicite vaut mieux qu'un paragraphe qui l'explique. Un commentaire au dessus d'une règle inhabituelle, disant pourquoi et non ce qu'elle fait, vaut mieux qu'une page d'architecture.
La règle : le document dit ce que le code ne peut pas dire, c'est à dire les raisons, les accès et l'historique. Tout le reste vieillit mieux dans le code.
Le test qui juge une documentation
Il est simple et impitoyable : donnez le système et sa documentation à quelqu'un d'extérieur, et demandez lui de faire une modification simple.
S'il y arrive en une journée, la documentation est bonne. S'il doit vous appeler trois fois, elle décrit ce que vous savez déjà et pas ce qu'il faut savoir.
Ce test se fait une fois, à la livraison, et il vaut mieux qu'une relecture. Nous le proposons systématiquement, y compris quand il nous met en défaut.
Ce que nous livrons
Les cinq pages, écrites pendant le projet et non après, avec le test de reprise à la livraison.
Et le principe qui les rend nécessaires : le code, les données et les accès vous appartiennent, et un autre prestataire peut reprendre l'ensemble sans notre autorisation. Une documentation qui ne permet pas cette reprise n'est pas une documentation, c'est une décoration.
Un système que personne ne comprend ?
Audit gratuit sous 48 heures, avec le test de reprise par un tiers
Demander un audit gratuit