La documentation technique que personne ne lit (et comment la rendre indispensable)

"On documentera plus tard." Cette phrase, je l'ai entendue dans chaque projet. Elle est toujours suivie du même résultat : plus tard n'arrive jamais. La documentation devient une dette qui s'accumule, jusqu'au jour où le seul qui connaissait le système part, et tout le monde découvre que le wiki est un cimetière de pages obsolètes datant de 2021.

Le problème n'est pas que les développeurs ne veulent pas documenter. Le problème, c'est que la documentation est conçue pour personne. Elle est écrite par obligation, stockée dans un endroit que personne ne visite, et mise à jour encore moins souvent que le code. Si votre documentation était un produit, aucun utilisateur ne l'utiliserait. Et c'est exactement ce qui se passe.

Pourquoi la documentation échoue

La documentation échoue pour trois raisons structurelles, pas culturelles :

Premièrement, elle est séparée du code. Le code est dans Git. La documentation est dans Confluence, ou Notion, ou un wiki MediaWiki oublié. Le code change. La documentation ne change pas. Dès le premier commit après la rédaction, la documentation est obsolète. Et plus le temps passe, plus l'écart grandit, plus personne ne fait confiance à la documentation, plus personne ne la lit, plus personne ne la met à jour. Cercle vicieux.

Deuxièmement, elle n'a pas de propriétaire. Qui est responsable de la documentation de l'API de paiement ? Personne. Le code a un auteur, une PR, un reviewer. La documentation a… un auteur qui l'a écrite il y a 18 mois et qui est parti depuis. Sans propriétaire, sans processus de mise à jour, la documentation est un artefact orphelin.

Troisièmement, elle est écrite pour le mauvais public. La documentation technique est souvent écrite comme si le lecteur connaissait déjà le système. "Le module X utilise le pattern Y pour gérer le Z." Si vous connaissez X, Y et Z, vous n'avez pas besoin de la doc. Si vous ne les connaissez pas, la doc ne vous aide pas. C'est un échec à deux niveaux.

Le cimetière wiki

Si votre documentation est dans un wiki, elle est déjà morte. Je le dis sans exagération. Le wiki est l'endroit où la documentation va mourir. Pas parce que les wikis sont mauvais — c'est un bon outil pour certains usages — mais parce que rien ne force la mise à jour. Un wiki est un jardin qu'il faut désherber. Personne ne désherbe. Le wiki devient une jungle de pages contradictoires, certaines à jour, certaines obsolètes, et personne ne sait lesquelles.

La confiance est le problème. Quand un développeur cherche une info, il a deux options : lire la doc, ou demander à un collègue sur Slack. Si la doc est à 50% fiable, le collègue est à 100% fiable. Le collègue gagne. Toujours. Et chaque question sur Slack est un échec de la documentation.

Les ADR : la documentation qui marche

Les Architecture Decision Records — ADR — sont la solution la plus simple et la plus efficace que j'ai vue pour documenter les décisions techniques. Un ADR est un court document (une page) qui décrit une décision d'architecture : le contexte, les options considérées, la décision prise, et les conséquences. Rien d'autre.

# ADR-007 : Choix de Redis pour le cache de session

## Contexte
Le système actuel utilise InProc session state, 
qui ne fonctionne pas en multi-instance.

## Options considérées
1. Redis — externe, rapide, persistant
2. SQL Server session state — simple, lent
3. Distributed cache en mémoire (Orleans) — complexe

## Décision
Redis. Bon équilibre performance/simplicité.

## Conséquences
- Nouvelle dépendance infrastructure (Redis cluster)
- Latence ~1ms par session read
- Nécessite un plan de failover Redis

Pourquoi les ADR marchent ? Parce qu'ils sont courts, datés, et stockés dans le repo de code, à côté du code qu'ils concernent. Quand un développeur ouvre un dossier de code, il trouve les ADR qui expliquent pourquoi ce code existe sous cette forme. Pas "comment" — le code le dit. "Pourquoi". Et le pourquoi, c'est ce que le code ne dit jamais.

Les ADR ne se mettent pas à jour. C'est voulu. Un ADR est un enregistrement historique d'une décision. Si la décision change, vous écrivez un nouvel ADR qui supersede l'ancien. L'ancien reste. Vous pouvez tracer l'évolution des décisions dans le temps. C'est de l'archéologie technique, et c'est inestimable pour les nouveaux qui veulent comprendre pourquoi le système est ce qu'il est.

Docs as Code : la documentation qui vit avec le code

Le principe de "Docs as Code" est simple : traitez la documentation comme vous traitez le code. Versionnée dans Git, revue en PR, testée en CI. Si la doc est dans le repo, elle change quand le code change — parce que le développeur qui modifie le code voit la doc à côté, et la PR inclut les deux.

Concrètement : un dossier /docs à la racine du repo. Des fichiers Markdown. Un build CI qui génère un site statique (MkDocs, Docusaurus, Antora) et le déploie. Des liens entre la doc et le code — des références aux fichiers, aux classes, aux lignes. Et un check CI qui vérifie que les liens ne sont pas cassés.

Le résultat ? La documentation est à côté du code. Elle change avec le code. Elle est revue avec le code. Elle est dans le même endroit que le code. Quand un développeur cherche une info, il cherche dans le repo — pas dans un wiki externe qu'il a oublié existe.

Le README-first approach

Avant d'écrire une ligne de code, écrivez le README. Le README décrit ce que le projet fait, comment l'installer, comment l'utiliser, comment contribuer. Si vous ne pouvez pas écrire le README, vous ne comprenez pas assez le projet pour le coder. C'est un exercice de clarification, pas de documentation.

Le README est la page d'accueil de votre projet. C'est la première chose qu'un nouveau développeur lit. Si le README est bon, le nouveau est autonome en une heure. Si le README est mauvais — ou n'existe pas — le nouveau pose sa première question sur Slack dans les 15 minutes. Et chaque question sur Slack est un échec du README.

Pourquoi la plupart des docs d'API sont terribles

La plupart des documentations d'API que je vois sont des listes d'endpoints. GET /users, POST /users, GET /users/:id. Avec les paramètres, les codes de retour, les schémas. C'est complet. C'est inutile. Parce que ça décrit l'API, pas comment l'utiliser.

Une bonne doc d'API commence par un scénario : "Vous voulez authentifier un utilisateur ? Voici comment." Avec un exemple complet, du curl au résultat. Pas une liste d'endpoints à assembler mentalement. La doc de Stripe est la référence : chaque page est un guide d'utilisation, pas une référence technique. La référence technique existe, mais elle est secondaire. Le guide d'utilisation est premier.

La distinction est cruciale : tutoriel (comment accomplir une tâche), guide (comment utiliser une fonctionnalité), référence (description exhaustive de l'API). Trois types de documentation, trois publics, trois formats. La plupart des docs d'API ne font que la référence, et c'est pourquoi personne ne les lit.

La documentation comme test

Le niveau ultime : traiter la documentation comme un test. Si votre doc contient des exemples de code, ces exemples doivent être exécutés en CI. Si un exemple ne compile pas ou ne marche pas, le pipeline casse. La doc ne peut pas être obsolète, parce que le CI la vérifie.

Des outils comme Doctest pour Python, rustdoc pour Rust, ou des scripts custom qui extraient les blocs de code de la Markdown et les exécutent. Le concept est simple : si la doc dit que le code fait X, le CI vérifie que le code fait X. Si le code change et que la doc ne suit pas, le pipeline casse.

C'est la seule façon de garantir que la documentation reste à jour : la rendre exécutable et la tester. Tout le reste repose sur la discipline humaine, et la discipline humaine est la première chose qui s'effondre sous la pression d'un sprint.