Documentation logicielle : quoi exiger de votre équipe technique

La documentation logicielle fait la différence entre posséder votre système et le louer à celui qui détient le savoir. Quoi exiger, et comment juger sa qualité, quand vous ne lisez pas le code.

Un fondateur avec qui nous avons travaillé a hérité d’une base de code quand son unique développeur est parti avec deux semaines de préavis. L’app tournait bien. C’était ça, le problème. Personne ne pouvait y toucher. Aucune note sur la façon de l’installer, aucune carte de l’assemblage des pièces, aucune trace de pourquoi le flux de paiement avait été construit de cette manière étrange. Le développeur suivant a passé cinq semaines à faire de la rétro-ingénierie sur ce que quelques pages de texte auraient expliqué en un après-midi. Le fondateur a payé deux fois : une fois en honoraires, une fois dans le lancement client qui a glissé.

La documentation logicielle est la trace écrite de la façon dont un système est construit, exploité et maintenu. Ce sont les instructions d’installation, la carte de la connexion des parties, les notes sur le pourquoi des décisions clés et les étapes pour exploiter et réparer la chose quand elle casse. Pour un fondateur non technique, la documentation n’est pas de la paperasse pour ingénieurs. C’est l’actif qui transforme votre base de code d’une boîte noire que vous louez en quelque chose que vous possédez vraiment. Une bonne documentation, c’est le développeur suivant qui reprend votre système en quelques jours. Une documentation mauvaise ou absente, c’est chaque personne qui touchera un jour à votre code qui vous tient en position de faiblesse.

Pourquoi cela vous concerne plus que les ingénieurs

Les ingénieurs débattent de la documentation comme d’une question de métier. Pour vous, c’est une question de contrôle. Tout système non documenté a exactement une sortie : la tête de celui qui l’a construit. Quand cette personne part, tombe malade ou oublie simplement, le savoir part avec elle. C’est le problème du bus factor, et la documentation en est l’assurance la moins chère.

C’est aussi la forme silencieuse du lock-in. Nous avons déjà écrit sur le fait que le vendor lock-in est un prix que vous payez pour rester. Le code non documenté est le même piège dans un autre habit. Vous n’êtes pas enfermé dans une plateforme ; vous êtes enfermé dans une personne ou une software house, parce qu’eux seuls savent déchiffrer ce qui existe. Le jour où vous voudrez un deuxième avis, une nouvelle équipe ou un devis juste pour étendre le produit, l’absence de documentation est ce qui rend le départ coûteux.

Rien de tout cela n’exige que vous lisiez une ligne de code. Cela exige que vous sachiez quels documents devraient exister et que vous insistiez pour qu’ils existent.

Les documents qu’un fondateur devrait vraiment exiger

Demandez à un ingénieur « les quatre types de documentation » et vous obtiendrez une taxonomie qui sert ceux qui écrivent de la documentation pour vivre. Voici la version qui sert celui qui paie la construction. Cinq documents couvrent presque tout ce qui compte.

Le guide d’installation, ou README. Comment un nouveau développeur met le système en marche sur sa propre machine, du début à la fin. Si un développeur compétent ne peut pas passer de zéro à une copie locale fonctionnelle en suivant ce seul fichier, il est incomplet. C’est le document le plus précieux, et celui qui manque le plus souvent.

La vue d’ensemble de l’architecture. Une carte courte et en langage clair des parties principales et de la façon dont elles se parlent. Quels sont les grands blocs, où vivent les données, ce qui se passe quand un utilisateur fait l’action centrale. Deux ou trois pages et un schéma. C’est ce qui permet à un nouveau développeur, ou à un CTO à temps partagé que vous faites venir, de comprendre votre système sans tout lire d’abord.

La documentation des intégrations et de l’API. Comment votre système se connecte au monde extérieur et comment ses propres parties se connectent entre elles. De quels tiers vous dépendez, ce qui casse si l’un d’eux change, où vivent les clés et les identifiants (les références, pas les secrets eux-mêmes). C’est la carte de vos dépendances, et c’est dans les dépendances que se cachent les surprises.

Les runbooks d’exploitation. Quoi faire quand quelque chose tourne mal à 2 heures du matin. Comment déployer un changement, comment restaurer depuis une sauvegarde, comment savoir si le système est en bonne santé. C’est la différence entre un incident qui dure vingt minutes et un qui dure un week-end.

Les registres de décision. De courtes notes sur le pourquoi des choix non évidents. Pourquoi cette base de données, pourquoi ce prestataire de paiement, pourquoi le contournement bizarre au checkout. Sans elles, le développeur suivant va « nettoyer » quelque chose de porteur et le casser, parce que personne n’a écrit que c’était là exprès.

Vous n’avez pas besoin que les cinq soient longs. Vous avez besoin qu’ils existent et soient à jour. Un README d’une page qui fonctionne vaut mieux qu’un manuel de cinquante pages que personne n’a mis à jour depuis la première version.

Combien de documentation logicielle suffit

L’instinct, une fois qu’un fondateur s’est brûlé, est d’exiger de la documentation sur tout. C’est une erreur en soi. La documentation, c’est du code qu’il faut maintenir, et sur-documenter un produit jeune qui change encore chaque semaine est un coût réel à courte durée de vie. Vous paierez pour écrire des pages qui décrivent des fonctionnalités que vous supprimez le mois suivant.

Le test honnête est une seule question : un développeur compétent qui n’a jamais vu ce système pourrait-il livrer un petit changement sûr dès sa première semaine, en n’utilisant que le matériel écrit et sans accès à celui qui l’a construit ? Si oui, votre documentation suffit pour son stade. Sinon, vous avez un trou, et il est exactement aussi coûteux que la section précédente l’a décrit.

Les prototypes jetables ont à peine besoin de docs, puisque vous comptez les jeter. À l’instant où le code passe en production et qu’un vrai client en dépend, le calcul s’inverse. C’est la ligne. Avant elle, gardez des notes. Après elle, exigez les cinq documents.

Comment distinguer une bonne documentation du théâtre

Vous ne lisez pas le code, donc vous ne pouvez pas noter les docs directement. Vous pouvez quand même les tester, et le test est bon marché. Quand vous intégrez un nouveau développeur ou évaluez une entreprise de développement logiciel, remettez-lui votre documentation et votre base de code et demandez combien de temps avant de pouvoir faire un petit changement en sécurité. Une réponse sûre et précise, qui cite votre vrai guide d’installation, est bon signe. Le flou, ou une demande de « juste caler un appel avec le développeur d’origine », vous dit que la documentation ne fait pas son travail.

L’autre indice est l’actualité. Ouvrez le guide d’installation et comparez la dernière fois qu’il a changé à la dernière fois que le code a changé. Une documentation qui n’a pas bougé depuis six mois pendant que le produit sortait chaque semaine est de la décoration, pas de la documentation. Les vrais docs sont mis à jour dans le même souffle que le code qu’ils décrivent. Demandez à celui qui construit pour vous de traiter une mise à jour de documentation comme une partie du « terminé », pas comme une faveur pour plus tard.

Write the Docs, la communauté des professionnels de la documentation, résume l’objectif simplement : la documentation doit permettre aux lecteurs de “réussir par eux-mêmes”. Si vos docs ne permettent pas à une nouvelle personne de réussir sans visite guidée, ils ne sont pas finis.

Qui l’écrit, et combien ça devrait coûter

Ceux qui écrivent la documentation sont ceux qui construisent votre logiciel. Pas un rédacteur technique à part, pas vous, et pas un stagiaire amené à la fin pour « documenter ce qui existe ». Le développeur qui a pris une décision est le seul à pouvoir l’expliquer à bas coût, et il ne le peut que tant qu’elle est fraîche. Une semaine plus tard, il l’a à moitié oubliée ; un mois plus tard, il devine comme tout le monde.

C’est pourquoi la documentation devrait vous coûter presque rien en tant que ligne de devis. Une équipe compétente l’écrit comme un sous-produit de la construction, dans les mêmes heures. Quand une software house facture la documentation comme une phase séparée et coûteuse à la fin, lisez-le comme un avertissement : cela veut dire en général qu’elle ne documente pas au fil de l’eau, ce qui veut dire que le reste du travail a la même qualité faite après coup. Le bon coût d’une bonne documentation est une petite taxe payée en continu, jamais une grosse facture payée d’un coup à la fin.

Mettez-le au contrat, pas dans l’espoir

La façon fiable d’obtenir de la documentation est de l’exiger avant que le travail commence, pas de la demander après. Quand vous fixez un périmètre avec un développeur ou une software house, nommez les livrables. Un produit fonctionnel et les cinq documents ci-dessus. Faites de « documentation à jour » une partie de ce que « terminé » veut dire à chaque jalon, comme vous définiriez tout autre critère d’acceptation dans un cahier des charges.

Cela ne vous coûte rien de plus si vous le dites dès le départ, parce qu’une équipe compétente documente au fil du travail. Cela coûte une fortune si vous le demandez à la fin, parce que reconstruire le raisonnement derrière six mois de décisions après coup est lent, mal vécu et souvent juste deviné. Les fondateurs qui ne se brûlent jamais avec un développeur qui part sont ceux qui ont fait de la carte une condition de la construction, pas un espoir pour plus tard.

La documentation est la ligne la moins glamour de tout projet logiciel et celle qui décide, plus que presque tout le reste, si ce que vous avez payé est un actif que vous possédez ou un passif que vous louez. Exigez la carte. Vous avez payé pour le territoire.

Questions fréquentes

Que signifie documentation logicielle ?
C’est la trace écrite de la façon dont un système logiciel est construit, exploité et maintenu : instructions d’installation, carte de la connexion des parties, notes sur le pourquoi des décisions clés et étapes pour l’exploiter et le réparer. Pour un fondateur non technique, c’est ce qui permet à un nouveau développeur de reprendre le système sans dépendre de celui qui l’a construit à l’origine.

Quel est un exemple de documentation logicielle ?
L’exemple le plus courant et le plus utile est un README : un seul fichier qui dit à un nouveau développeur exactement comment mettre le système en marche sur sa propre machine, étape par étape. D’autres exemples sont une vue d’ensemble de l’architecture (une carte en langage clair des parties principales), la doc d’intégration (comment il se connecte aux tiers), les runbooks d’exploitation (quoi faire quand quelque chose casse) et les registres de décision (pourquoi des choix non évidents ont été faits).

Quels sont les quatre types de documentation ?
Les ingénieurs citent souvent des types comme tutoriels, guides pratiques, référence et explication. La version qui compte pour un fondateur qui paie la construction, ce sont cinq documents : un guide d’installation (README), une vue d’ensemble de l’architecture, la doc d’intégration et d’API, les runbooks d’exploitation et les registres de décision. Ils couvrent le savoir qui, sinon, ne vivrait que dans la tête d’un développeur.

De combien de documentation une petite startup a-t-elle besoin ?
Assez pour qu’un développeur compétent qui n’a jamais vu le système puisse livrer un petit changement sûr dès sa première semaine en n’utilisant que le matériel écrit. En dessous de ce seuil, vous avez un risque ; au-dessus, vous sur-documentez probablement un produit qui change encore. Les prototypes jetables ont à peine besoin de docs ; tout ce dont dépend un client payant a besoin de l’ensemble essentiel.

Quel logiciel a la meilleure documentation ?
C’est une question d’outil, et c’est la mauvaise pour un fondateur. La qualité de votre documentation dépend de la discipline de celui qui l’écrit, pas de l’outil où elle vit. Un README à jour et clair dans un wiki simple vaut mieux qu’une plateforme de documentation sophistiquée pleine de pages périmées. Jugez l’habitude, pas le logiciel.

Comment m’assurer que mon développeur documente vraiment ?
Exigez-le avant que le travail commence. Nommez les documents comme livrables dans votre cahier des charges et faites de « documentation à jour » une partie de ce que « terminé » veut dire à chaque jalon. Une équipe compétente documente au fil de la construction, à presque aucun coût supplémentaire. Le demander seulement à la fin, c’est là que la documentation devient chère, mal vécue et peu fiable.