Documenter un dépôt qu'on ne connaît pas

1Décider à qui la documentation s'adresse

Documenter tout le dépôt est un objectif qui garantit un document que personne ne lira. Une documentation utile répond aux questions d'un lecteur précis.

Trois lecteurs, trois documents différents :

Choisis-en un, écris pour lui, et arrête-toi. Les deux autres viendront après si le besoin existe.

2Établir les faits avant de demander une synthèse

Un agent qui lit un gros dépôt d'un coup en retient une impression générale, et c'est de cette impression que naissent les inventions. Donne-lui d'abord des faits mesurables.

L'historique git est la source la plus honnête d'un dépôt, parce qu'il enregistre ce qui s'est passé et non ce qu'on a voulu croire.

git shortlog -sn
git log --since="12 months ago" --name-only --format="" | sort | uniq -c | sort -rn | head -40

La première commande supprime la description des commits et donne un décompte par auteur, trié par nombre de commits. La seconde donne les fichiers les plus modifiés sur un an : c'est la carte du code vivant, et elle diffère presque toujours de la structure des dossiers.

Deux autres questions se répondent avec git log :

• git log -S"NOM" cherche les commits dont le correctif ajoute ou retire des lignes contenant une chaîne. C'est ce qui permet de retrouver quand et pourquoi une option est apparue.
• git log --since=... sur un dossier précis dit s'il est encore maintenu ou s'il est mort.

3Demander une carte, pas une prose

La première production utile n'est pas un texte, c'est un inventaire. Un tableau se vérifie ligne par ligne, un paragraphe ne se vérifie pas.

Explore ce depot et rends-moi un tableau : chemin du dossier, role apparent,
fichier principal, date du dernier commit. Une ligne par dossier de premier
niveau. Pour la colonne role, si tu n'es pas sur, ecris "indetermine"
plutot que de deduire d'apres le nom du dossier.

La dernière contrainte fait tout le travail. Sans elle, un dossier nommé utils sera décrit comme « fonctions utilitaires partagées », ce qui est une paraphrase du nom, pas une observation.

Puis on descend, un sujet à la fois :

Trace le chemin complet d'une requete [METHODE] [ROUTE] : chaque fichier
traverse, dans l'ordre, avec le numero de ligne de la fonction concernee.
Si le chemin se perd, dis ou et pourquoi.

4Exiger une citation pour chaque affirmation

C'est la règle qui sépare une documentation vérifiable d'un texte plausible. Chaque affirmation factuelle doit renvoyer à un fichier et une ligne.

Pour chaque phrase de cette documentation qui affirme un fait sur le code,
ajoute entre parentheses le fichier et la ligne qui le prouve. Si tu ne
peux pas citer de source pour une phrase, supprime-la et liste-la a part
sous le titre « a verifier ».

La liste « à vérifier » est le vrai livrable de cette étape. Elle contient exactement ce que le modèle a déduit plutôt que lu, c'est-à-dire ce qui risque d'être faux.

5Vérifier à la main ce qui ne se vérifie qu'à la main

Il existe une catégorie d'affirmations qu'aucune lecture de code ne valide, parce qu'elles portent sur l'exécution. Elles se testent, une par une.

1. Les commandes d'installation et de démarrage. Lance-les dans un dossier vierge, sans ton cache et sans tes variables d'environnement déjà en place. C'est le test le plus rentable de toute la liste.
2. La liste des variables d'environnement. Un modèle la reconstitue à partir des occurrences trouvées dans le code, et rate celles qui sont lues indirectement ou définies dans l'infrastructure. Vérifie qu'aucune n'est inventée, et cherche celles qui manquent.
3. Les versions requises. Le langage, l'exécution, la base de données. Une version annoncée de mémoire est presque toujours fausse.
4. Les points d'entrée exposés. Appelle-les. Un endpoint documenté qui renvoie 404 est le symptôme le plus courant d'une documentation générée.
5. Les effets de bord. Ce qui écrit dans une base, envoie un message ou appelle un service externe. C'est ce que le lecteur a le plus besoin de savoir, et c'est le moins visible dans le code.

6Documenter le pourquoi, qui n'est nulle part

Un agent lit très bien ce que fait le code. Il ne peut pas savoir pourquoi il le fait ainsi, parce que cette information n'a jamais été écrite.

Ce sont pourtant les paragraphes les plus utiles d'une documentation : pourquoi cette dépendance plutôt qu'une autre, pourquoi ce contournement bizarre, pourquoi cette table n'est pas normalisée, quelle contrainte externe a imposé ce choix. Ces réponses sont dans la tête des gens, ou dans les messages de commit et les tickets. Nulle part ailleurs.

La bonne division du travail est donc celle-ci : l'agent produit la carte, les chemins, les inventaires, tout ce qui se déduit du code. Toi, tu ajoutes les décisions et leurs raisons, en quelques lignes chacune. Quand tu ne connais pas la raison, écris-le explicitement plutôt que de la reconstituer : « le choix de X n'est pas documenté » est une information exacte et utile, contrairement à une justification inventée après coup.