Rédaction de documentation technique
Compiler la documentation technique en un support de connaissance stable, maintenable et facile à naviguer. D'abord, décider à quel endroit appartiennent les faits et ce dont le lecteur a besoin, puis organiser le contenu, et enfin peaufiner l'expression.
Principes fondamentaux
- Avant d'écrire, identifier le type d'information ; ne pas transformer le processus de découverte directement en structure d'article.
- Chaque fait persistant possède un seul propriétaire canonique ; le propriétaire peut être le code source, la configuration, le schéma, un générateur, la documentation ou un enregistrement de décision.
- Choisir le type de document en fonction de l'intention du lecteur, et non en fonction du nom de fichier ou des documents existants.
- Avant de commencer à écrire, établir un Contrat de Documentation : lecteur, objectif, sujet, périmètre, exclusions, sources faisant autorité et plafond de détails.
- Le type de document ne peut pas étendre le périmètre ; les documents de niveau supérieur résument leurs enfants directs et pointent vers les propriétaires des détails.
- Organiser le contenu par prérequis, dépendances et résultats vérifiables, et non par ordre d'investigation, de mise en œuvre ou de soumission.
- Placer l'état actuel, la justification de la conception et le récit historique dans des responsabilités documentaires distinctes.
- Lors d'un changement de frontière, créer des liens vers les détails faisant autorité, ne conserver que le contenu qui correspond au périmètre actuel et qui est suffisamment stable.
- L'agent principal fige d'abord le plan de rédaction, puis décide de la délégation ; les sous-agents n'exécutent que des tâches d'écriture locales dont les limites sont claires.
Contrat de travail
Avant d'effectuer une écriture, une réécriture, une scission, une fusion ou une révision structurelle, élaborer un Contrat de Documentation succinct. Il peut être réalisé en interne ; ne le transformer en artefact visible que si la tâche nécessite un alignement.
Enregistrer les champs suivants :
- Intention du lecteur : Le lecteur souhaite-t-il apprendre, accomplir une tâche, consulter, comprendre, retracer ou se conformer à une règle.
- Type de document : Le type de document principal correspondant à l'intention ; un document ne conserve qu'une seule intention principale.
- Sujet : Le thème ou le niveau du système dont le document est directement responsable.
- Périmètre : Les objets, comportements et profondeur inclus.
- Exclusions : Le contenu explicitement laissé à d'autres documents ou sources faisant autorité.
- Sources faisant autorité : Le code source, la configuration, les fichiers générés, les enregistrements de décision ou les documents existants qui soutiennent les faits actuels.
- Plafond de détails : Le niveau de détail le plus élevé autorisé pour le sujet actuel et les objectifs du lecteur.
S'il est impossible de déterminer le propriétaire, l'intention du lecteur, le périmètre ou les sources faisant autorité, conserver d'abord l'incertitude et signaler les lacunes ; ne pas inventer de décisions sur le produit ou le comportement actuel par expérience.
Flux de travail de rédaction
1. Localiser la tâche et la position du document
Identifier s'il s'agit d'une création, d'une mise à jour, d'une scission, d'une fusion ou d'une révision structurelle. Lire les fichiers pertinents tels que AGENTS.md, CLAUDE.md, CONTEXT.md, l'index de la documentation et les documents adjacents pour confirmer les conventions de hiérarchie, de nommage et de lien déjà en place dans le dépôt.
Si le document cible n'existe pas, traiter la tâche comme une documentation greenfield : établir une carte documentaire candidate à partir des répertoires de code, des API publiques, des schémas de configuration, des tests, des exemples, des commandes et des fichiers générés. D'abord, déterminer si un seul document d'entrée ou un ensemble de documents divisés par propriétaire et intention du lecteur est nécessaire ; ne pas compresser l'ensemble du cadre de code en un seul document volumineux et exhaustif.
Condition d'achèvement : Si un document existe déjà, connaître le chemin cible, le document parent, les enfants directs et les règles locales applicables ; s'il n'y a pas de document existant, connaître les principales limites du cadre de code, l'ensemble candidat de documents, le propriétaire préliminaire de chaque document et les sources faisant autorité.
2. Inventorier et classer les informations
Lister les faits, explications, étapes, exemples, contraintes et éléments historiques à conserver. Les classer par type d'information, en distinguant l'état actuel, la justification persistante, le processus opérationnel, les données de référence, les règles, les incidents et le contenu généré.
Si un tableau de classification détaillé est nécessaire, lire references/information-and-ownership.md.
Condition d'achèvement : Chaque élément de contenu candidat possède un type d'information ; aucun mélange de différents types de matériaux dans un paragraphe non défini.
3. Router les faits vers le propriétaire canonique
Pour chaque fait persistant, rechercher un propriétaire existant. Utiliser d'abord le code source, la configuration, les schémas, les générateurs et les enregistrements de décision existants comme sources faisant autorité ; la documentation ne détient que les interprétations, les processus ou les contrats stables relevant de sa responsabilité.
Pour le contenu dont le propriétaire existe déjà, ne conserver qu'un résumé nécessaire et un lien vers le propriétaire. Si plusieurs propriétaires conflictuels sont découverts, signaler d'abord le conflit et enregistrer le problème d'autorité à résoudre.
Condition d'achèvement : Chaque fait non trivial a un et un seul propriétaire ; le document actuel ne duplique pas les détails faisant autorité provenant d'ailleurs.
4. Choisir le type de document en fonction de l'intention du lecteur
Choisir parmi les types de document suivants en fonction de l'objectif du lecteur : Didacticiel, Procédure, Référence, Explication, Registre de décision architecturale (ADR), Politique ou Post-mortem. Ne pas attribuer plusieurs types principaux à un fichier simplement parce qu'il contient plusieurs types de contenu ; lorsque l'intention mixte atteint un niveau qui nuit à la navigation ou à la maintenance, scinder le document.
Lire references/document-types-and-composition.md pour obtenir les types et les modèles de structure.
Condition d'achèvement : Pouvoir dire en une phrase « Qui lit ce document et pourquoi », et identifier un type de document principal.
5. Fixer le périmètre et le plafond de détails
Écrire le sujet, le public, l'objectif, les éléments inclus, les exclusions, les sources faisant autorité et le plafond de détails. Limiter le document à son propre sujet, à son niveau et aux responsabilités de ses enfants directs ; déplacer les mécanismes de niveau inférieur, les tests, les listes de contrôle et les détails d'implémentation vers leur propriétaire.
Le type de document ne peut pas étendre le périmètre. Les documents parents décrivent la composition, les responsabilités et les comportements de haut niveau ; les documents enfants possèdent les définitions de types, les paramètres, les mécanismes de test ou les opérations spécifiques.
Condition d'achèvement : Chaque section peut répondre à la question « Comment sert-elle l'intention actuelle du lecteur et le périmètre ? » ; le matériau hors limites a déjà une destination ou un lien.
6. Élaborer un plan de rédaction exécutable
D'abord, organiser les concepts préalables que le lecteur doit connaître, puis organiser les opérations, explications ou requêtes qui en dépendent. Utiliser la structure correspondant au type de document, ne pas suivre l'ordre d'investigation, de mise en œuvre, de discussion ou de soumission comme ordre pédagogique.
Pour les grands documents, enregistrer l'arborescence des sections, les propriétaires des faits, les dépendances entre sections, le fichier cible, les exclusions et les conditions d'acceptation de chaque section. Le plan doit permettre à un autre agent d'exécuter une tâche locale sans avoir à reconcevoir la structure globale.
Condition d'achèvement : Le lecteur n'a pas besoin de sauter plus loin pour comprendre les termes nécessaires, les prérequis ou les actions d'une section ; chaque paragraphe principal répond à une question claire ; chaque unité planifiée a un périmètre et des conditions d'achèvement uniques.
7. Choisir le mode d'exécution et déléguer
Par défaut, emprunter le chemin de l'agent unique. N'activer les sous-agents que si les conditions suivantes sont toutes remplies :
- Le plan est déjà figé, il n'y a pas de conflit non résolu concernant l'intention du lecteur, le type de document, le périmètre, le propriétaire et la structure principale.
- Il existe au moins deux unités de travail pouvant être lues, écrites et validées indépendamment.
- Chaque unité de travail a un fichier cible ou un propriétaire de section unique, et les tâches ne modifient pas simultanément le même texte.
- Les dépendances sont explicitement enregistrées ; les faits à partager ont déjà une source faisant autorité, et ne dépendent pas d'estimations mutuelles entre sous-agents.
- Le coût de répartition et de fusion est inférieur au coût pour l'agent principal de porter tout le contexte du document en continu.
Lorsque les conditions sont remplies, lire references/orchestration-and-delegation.md ; l'agent principal génère un briefing de répartition et appelle les sous-agents. L'agent principal conserve le plan global, l'attribution des faits, les liens entre sections, les décisions de fusion et le droit de validation final. Les sous-agents ne reconçoivent pas le type de document, ne modifient pas d'autres unités de travail et ne présentent pas de faits non vérifiés comme des conclusions.
Lorsque les conditions ne sont pas remplies, l'agent principal continue la rédaction seul. Les ajouts locaux à un fichier unique, les révisions de quelques paragraphes, les mises à jour de Référence avec un seul propriétaire et les dépendances fortement séquentielles relèvent du chemin de l'agent unique.
Condition d'achèvement : Le choix entre exécution mono-agent ou déléguée est clair ; en cas de délégation, chaque tâche a des limites, des dépendances, un format de sortie et des conditions d'acceptation.
8. Écrire directement le contrat actuel et le comportement observable
Exprimer le contenu avec des sujets, actions, API, options et résultats concrets. D'abord, écrire l'état actuel et le comportement observable par le lecteur, puis ajouter les valeurs par défaut, les limites, les exceptions, la justification et les compromis. Distinguer clairement entre « doit », « par défaut », « recommandé » et « peut ».
Les didacticiels et les procédures peuvent centrer l'explication sur un exemple minimal ; les Références se concentrent sur les définitions et les limites consultables ; les ADR et les Post-mortems conservent leurs justifications ou chronologies respectives.
Si des règles complètes et des listes de contrôle sont nécessaires, lire references/writing-and-validation.md.
Condition d'achèvement : Le texte énonce des faits, des contrats ou des étapes maintenables, et non un processus de raisonnement, un journal d'implémentation ou un métadiscours vague ; les sorties des tâches déléguées ont toutes été réintégrées par l'agent principal.
9. Fusionner et unifier
Si des sous-agents ont été utilisés, l'agent principal vérifie chaque sortie par rapport au plan de rédaction. Résoudre les faits en double, les dérives terminologiques, les limites de sections, les liens croisés et les incohérences stylistiques ; regrouper les problèmes non résolus, ne pas laisser un agent local inventer des décisions globales. Ne pas intégrer directement les explications de processus des sous-agents dans le texte principal, ne fusionner que les résultats maintenables.
Condition d'achèvement : Chaque unité déléguée a un résultat ou une raison de blocage claire ; un même fait n'a pas plusieurs propriétaires ; la table des matières globale, les liens, la terminologie et le chemin du lecteur sont cohérents.
10. Lier, réduire et valider
Supprimer les faits en double, les listes recopiées, les informations de contexte non pertinentes et les détails dépassant le plafond de détails. Créer des liens vers le propriétaire, les documents enfants, le code source et les enregistrements de décision en expliquant l'objectif. Effectuer une validation structurelle et linguistique dans l'ordre fourni par les fichiers de référence.
Condition d'achèvement : Le propriétaire, le type, le périmètre, l'ordre des dépendances, les limites entre l'état actuel et l'historique, les liens et les règles d'expression ont tous été vérifiés ; aucun conflit ou incertitude non résolu ne subsiste.
Limites
Ne pas écrire comme règles générales la hiérarchie de fichiers propre au dépôt, les commandes de script, le budget de mots, les règles de compilation de blocs de code, les processus bilingues ou la terminologie spécifique. Lire les conventions locales du projet et s'y conformer ; cette compétence ne fournit qu'un cadre de décision documentaire stable d'un projet à l'autre.
Ne pas traiter README, architecture.md ou AGENTS.md comme des types de documents génériques fixes. D'abord, déterminer l'intention du lecteur, puis suivre les conventions spécifiques du projet concernant ces supports.
Remise finale
À la fin, fournir une brève explication : le type de document et l'intention du lecteur, le traitement du propriétaire canonique, les limites du périmètre, les liens ou les scissions impliqués, ainsi que les conflits factuels nécessitant encore une décision humaine. Ne pas présenter des problèmes non résolus comme l'état actuel.