La doc que lit votre copilote est celle que lit votre nouvelle recrue
Le premier lundi d'une nouvelle recrue est un test de charge pour votre documentation, et il l'a toujours été. Ce qui a changé, c'est qui d'autre s'assied dans la pièce. Le paragraphe qui échoue à expliquer le renouvellement de jeton à quelqu'un qui débarque se retrouve collé dans un assistant de code, et ce que l'assistant construit à partir du collage finit dans une pull request avant le déjeuner. Un document, deux lecteurs, et un seul lève la main quand il n'a pas compris.
La thèse, dite simplement : une équipe n'a pas besoin de deux documentations, une pour les humains et une pour les machines, parce que ce qu'exige un lecteur modèle, c'est ce qu'exige un lecteur humain pressé, appliqué plus sévèrement. Quatre habitudes de rédaction survivent à un humain patient et échouent devant un modèle. Les corriger coûte un après-midi d'édition, et le document corrigé est celui qu'une nouvelle recrue peut suivre sans la séance de tableau blanc. Une deuxième doc, condensée pour les agents, c'est l'expérience ratée que nous avons menée en premier, et elle aura sa partie plus bas.
Quatre habitudes que les humains pardonnent et que les modèles punissent
La première habitude, ce sont les titres qui ne veulent rien dire hors du contexte. Une section nommée « Notes » sous « Authentification » parle peut-être du décalage d'horloge entre le serveur de jetons et la base, mais le titre voyage seul. Un humain qui lit de haut en bas emporte le contexte avec lui ; un modèle qui récupère un paragraphe, ou vous le cite dans une discussion, n'a que ce que le paragraphe lui-même déclare. Écrivez chaque titre comme si le lecteur arrivait en hélicoptère : « Décalage d'horloge entre le serveur de jetons et la base » fonctionne à toute altitude, « Notes » non.
La deuxième habitude, c'est pointer la page au lieu de l'adresse. « Comme dit plus haut », « dans la section précédente », « ce dernier » : les trois supposent un lecteur linéaire avec une bonne mémoire de travail. Le lecteur qui ne tient qu'un extrait ne retient rien. Le lecteur humain en diagonale, qui lit aussi votre document, a renoncé à remonter trois paragraphes plus tôt. Référencez par nom et par emplacement : titre de la section, ancre, URL. La règle coûte quelques mots et achète un document qui survit à une lecture en morceaux, ce que vos deux publics font réellement.
La troisième habitude, c'est la capacité sans valeur par défaut. « La fenêtre de renouvellement est configurable » est vrai et inutile, parce que le lecteur suivant, humain ou modèle, doit inventer un chiffre, et il en invente un dont il est sûr. Écrivez le défaut sur la ligne du réglage, plus l'unique condition qui justifierait de le changer. Un défaut écrit à côté de son réglage reste trouvable le jour où quelqu'un doit décider si le défaut est le problème.
La quatrième habitude, c'est renvoyer vers un autre document pour la chose même que le lecteur cherchait. « Si le renouvellement échoue, voir le guide d'auth » envoie le lecteur vers un guide qui rend la même phrase. Les modèles suivent les cercles aussi patiemment que les humains, et aucun des deux ne trouve de réponse au bout de la boucle. Réglez la référence circulaire sur la page où le lecteur se trouve, et laissez les liens porter la profondeur plutôt que la réponse.
Donnez à chaque section une adresse, puis cessez de la déplacer
Un titre, une fois publié, est une adresse, et la promesse est que cette adresse ne bouge pas. Les deux lecteurs vous croient sur parole. La recrue note les titres de sections dans ses notes dès la première semaine, et l'assistant les garde comme les étiquettes qu'il citera des mois durant. Renommez un titre et vous cassez quelque chose sans message d'erreur : le guide opératoire qui renvoie le budget de reprise à la section « cycle de vie du jeton », le commentaire de ticket qui pointe #token-lifecycle, la réponse d'assistant construite sur l'ancienne formulation. Vu de 2 h du matin, l'échec est mécanique : une recherche « lifecycle » renvoie désormais un billet de 2023, et c'est ce que lit l'ingénieur d'astreinte.
Renommer est donc une migration, et les migrations ont leurs listes de contrôle. Chaque référence croisée est mise à jour dans le même commit, chaque lien externe trouvable est redirigé, et l'ancien texte du titre devrait apparaître une fois, dans la nouvelle section, recopié tel quel pour les lecteurs et les systèmes d'extraction qui gardent encore l'ancienne adresse. Le parallèle humain est exact : les notes internes d'une équipe pourrissent le jour où les titres s'agitent. Un titre que vous gardez est de l'infrastructure. Un titre que vous renommez sans liste de contrôle est un lien cassé dont personne ne vous a encore parlé.
Un seul sens par mot
Dans un dépôt, chaque concept reçoit un nom. Si une session et un jeton sont deux choses différentes, une phrase le dit une seule fois : « Une session contient un ou plusieurs jetons, et un refresh token survit à son access token. » À partir de là, ces mots ne veulent dire que cela. Le « credential » du guide opératoire et celui du guide d'accueil désignent le même objet, ou la différence est écrite, parce que l'assistant qui joint vos documents entre dépôts n'a aucun moyen de deviner si le vocabulaire a glissé d'un fichier à l'autre.
Là où l'histoire impose deux noms à une seule chose, déclarez l'alias au lieu de le cacher : « Le guide de migration appelle cet objet un ticket. C'est la même chose, renommée en 2025. » Une phrase honnête vaut mieux qu'un glossaire que personne n'ouvrira. Le test de tout paragraphe est le test de la citation : copiez le paragraphe, seul, dans une discussion avec quelqu'un qui n'a pas lu la page qui l'entoure, et demandez-vous s'il garde exactement un sens. S'il survit, le modèle qui lit votre dépôt survit aussi. S'il ne survit pas, le défaut que vous venez de corriger pour la machine est celui qui vous coûtait une heure d'accueil.
Des exemples qui apportent leur sortie attendue
Un exemple n'est pas fini tant qu'il ne dit pas ce que le succès imprime. Le contraste ci-dessous, épinglé chez nous, est condensé d'une retouche de guide opératoire :
## Gotchas
Auth: see above. If refresh stops working, ask in #platform.
## Token refresh, and when a request uses the old token
The client refreshes a token when it is within 60 seconds of expiry.
A request already in flight keeps using the old token, which stays
valid for 5 minutes after the refresh.
Default: 60 s. Change it only if an idle connection is dropped by
your load balancer sooner than the 60 s window.
La deuxième section peut être citée n'importe où sur la planète et instruire quand même. Elle a une adresse, un comportement fixé, un défaut, et la condition pour changer le défaut. Elle porte aussi son propre test : lancez la procédure, comparez la sortie, et la documentation correspond au système ou dépose un bug. Un exemple relié à la CI pourrit en build rouge plutôt qu'en mauvaise réponse servie à un lecteur, humain ou modèle ; voilà pourquoi le bon paragraphe ci-dessus est écrit tel quel. Un exemple sans sa sortie attendue demande au lecteur de fournir la réponse. Avec elle, l'exemple peut être vérifié, relancé et noté.
L'expérience des deux copies, retirée
Voici le regret promis. Nous avons écrit la copie condensée pour agents : une version plus courte, à l'impératif, d'un document d'architecture, débarrassée du récit, taillée pour l'extraction. Pendant deux semaines, cela ressemblait à l'avenir. Puis le document source a changé sa fenêtre de renouvellement, et la copie condensée a gardé l'ancien chiffre, parce qu'un résumé n'a pas de CI. La page qui se contredisait avec le système était précisément celle qu'un assistant a citée, avec le chiffre périmé, dans une revue de code, et nous avons corrigé en supprimant la copie, pas en ajoutant un job de synchronisation. Une source unique de vérité, appliquée par la même CI que le code, a gagné sur la maintenance seule.
Les retouches qui ont survécu à la suppression étaient petites et mécaniques : des titres qui voyagent, des défauts sur la ligne, des alias déclarés, des exemples avec sortie. Ce qui a changé pour les humains était plus silencieux. La photo du tableau blanc a cessé d'être la seule copie du comportement de renouvellement du jeton, parce que ce comportement existe désormais, vérifiable, dans le guide opératoire. Les questions des recrues sont passées de « où c'est écrit » à « pourquoi c'est ainsi », la conversation qui vaut la peine le premier jour. Personne n'a mesuré les minutes gagnées, et nous n'inventerons pas de chiffres ici : le changement observable, c'est quelles questions se posent.
Ce qu'un document précis ne peut toujours pas faire
Un document précis rend la réponse d'un assistant traçable, pas correcte. L'extraction peut toujours ramener le mauvais paragraphe ; un modèle peut encore mal lire une phrase que vous jugiez sans ambiguïté ; et aucun de ces deux échecs ne se déclare. Le contournement est le même pour les deux lecteurs, et il dit pourquoi les ancres comptent plus que le poli de la prose : une réponse fausse se confronte à son paragraphe d'origine en un clic, ou ne le peut pas, et cette différence, c'est vous qui l'avez dessinée. L'intention reste hors du document. « Faut-il renouveler de façon proactive ou laisser les requêtes basculer » n'est pas de la syntaxe, le modèle ne vous demandera pas ce que vous vouliez dire, et la recrue non plus le premier jour. Cette question-là est le motif de la première rencontre avec un humain. Le document a pour travail de rendre superflu tout ce qui précède cette question, pour que la réunion commence là où il faut un humain.
La conclusion tient sur une ligne, appliquée au paragraphe ouvert dans votre éditeur : chaque titre voyage-t-il, chaque renvoi pointe-t-il vers une adresse, chaque configurable porte-t-il son défaut sur la ligne, chaque exemple imprime-t-il à quoi ressemble le succès. Corrigez ces quatre points et vous avez fini, parce que vous aurez écrit un seul document que les deux lecteurs savent suivre. N'écrivez pas la deuxième copie. Nous l'avons écrite pour vous, puis nous l'avons supprimée.
AngoraTek écrit la documentation comme partie intégrante de la livraison, sur l'idée qu'une même page doit servir la recrue et les outils qui la lisent. S'il existe une section que votre équipe réexplique sans cesse, [amenez-nous cette section](/fr/#contact) et nous la ferons voyager.Merci d'avoir lu jusqu'ici. Si cela ressemble au problème sur lequel vous butez, parlez-nous-en. L'équipe lit chaque message.
Engager la conversation