doc-refine — Guide d'optimisation de l'expérience de lecture de la documentation technique
Limites de la révision et de la réécriture
Distinguer d'abord révision et réécriture : lorsque seule une révision est demandée, fournir les problèmes et suggestions ; lorsque la modification est explicitement demandée, ne modifier que les documents autorisés. Si le changement concerne un comportement ou un fait plutôt qu'un ajustement d'expression, conserver le sens original et indiquer les parties nécessitant une confirmation.
Protéger avant la simplification : comportements techniques, contrats API/données, prérequis et conditions limites, avertissements de sécurité et juridiques, descriptions alternatives d'accessibilité, exemples valides, liens sources et ancres stables. Le fait que le comportement existe déjà dans le code ne suffit pas à justifier la suppression de la documentation ; une répétition locale nécessaire peut aider à une lecture indépendante.
Deux objectifs de vérification
Tous les jugements se réduisent finalement à deux questions :
| Axiome | Question à se poser | En une phrase |
|---|---|---|
| ① Trouver rapidement | Le lecteur cible peut-il déterminer où se trouve l'information à partir de la table des matières et des titres ? | Signalisation claire |
| ② Chaque paragraphe a un but | La suppression de ce passage entraîne-t-elle une perte d'informations nécessaires pour accomplir une tâche, comprendre un comportement ou maîtriser les risques ? | Information complète et concise |
Effectuer ces deux vérifications sur chaque contenu. Ne pas satisfaire ① → modifier le titre / ajouter un diagramme / réorganiser la structure. Ne pas satisfaire ② → vérifier les éléments protégés et la tâche du lecteur, puis suggérer une fusion ou une simplification ; ne pas supprimer le contenu nécessaire pour des raisons de longueur.
Flux de travail
1. Diagnostic (lire d'abord l'intégralité du document, ne pas modifier immédiatement)
Lire le document cible en entier, section par section, et noter les problèmes :
- Le titre peut-il transmettre le contenu de manière indépendante, sans numérotation ? (Non → violation de l'axiome ①)
- La même logique/règle apparaît-elle à 2+ endroits ? (Oui → violation de l'axiome ②)
- Cette description de comportement aide-t-elle l'utilisateur à comprendre le contrat, les limitations ou les résultats ? Juger d'abord l'utilité, ne pas supprimer mécaniquement selon « quoi/pourquoi ».
- Les phrases d'introduction ne sont-elles que des répétitions préparatoires ? Peut être simplifié dans la formulation, mais conserver les indications de localisation des étapes, les avertissements ou les limitations.
- Des comparaisons de 3+ éléments sont-elles dispersées dans de la prose ? (Oui → utiliser un tableau)
- Un diagramme est-il plus facile à comprendre qu'un texte pour un processus ou un état ? Choisir Mermaid ou conserver le texte selon les capacités du moteur de rendu cible.
- L'exemple résout-il une vraie question, une récupération d'erreur ou un cas limite ? Conserver les exemples pertinents pour le lecteur cible.
2. Correction (appliquer les règles classées par axiome)
Voir les règles détaillées ci-dessous aux §Axiome ① et §Axiome ②.
3. Validation (référence quantitative)
Après correction, lire la liste de vérification selon les besoins pour vérifier l'exhaustivité des informations et l'effet de la lecture. Tous les chiffres ne doivent pas nécessairement être atteints — ce sont des outils de diagnostic, pas des lois ; la clarté prime, et des exceptions peuvent être faites.
Axiome ① : Trouver rapidement
Reconnaissabilité des titres
Un titre est un repère. Lorsqu'un mainteneur parcourt la table des matières, il doit immédiatement savoir ce que contient chaque section.
Critère de jugement : Si vous devez cliquer dans la section pour savoir de quoi elle parle, le titre est trop vague.
| ❌ Trop vague | ✅ Reconnaissable | Pourquoi changer |
|---|---|---|
5.1 Niveau table | 5.1 CRUD du projet (endpoint niveau table) | « Niveau table » pourrait être n'importe quoi |
5.3 Niveau ligne | 5.3 Endpoint de collaboration niveau ligne | Le lecteur sait qu'il y a des opérations comme la revendication/livraison |
5.4 Export | 5.4 Export CSV complet | Quel format ? Complet ou partiel ? |
Endpoint | Endpoint HTTP | Levée d'ambiguïté |
Astuce : lorsqu'un concept central est trop court, ajouter des qualificatifs entre parenthèses pour compléter les informations clés. Mais ne pas en faire trop — l'objectif est de transmettre « ce que contient cette section » en ≤15 mots, pas d'écrire un titre de thèse.
Architecture de l'information
- Une section, une fonction : Organiser le contenu selon la tâche principale du lecteur (tutoriel, opération, référence ou explication) ; les signatures API ou brèves informations contextuelles peuvent être conservées, les documents longs utilisent des liens croisés.
- Contenu principal en premier, détails ensuite : Placer les informations les plus importantes en début de section ou en haut du document (Progressive Disclosure). Les informations avancées/marginales peuvent être pliées ou mises en annexe.
- Principe d'autonomie : Un mainteneur peut commencer à lire à partir de n'importe quelle page sans avoir besoin de « connaissances préalables » (Every Page is Page One). Lorsqu'un concept préalable est nécessaire, le déclarer en haut de la section et ajouter un lien.
Texte alternatif pour les diagrammes
Utiliser des diagrammes lorsque les relations, les séquences ou les comparaisons sont plus claires visuellement ; conserver le texte pouvant être recherché et les descriptions alternatives nécessaires.
Arbre de décision :
Le type d'information est ?
├─ Processus multi-étapes / avec décisions conditionnelles → Diagramme de flux (flowchart)
├─ Changement d'état piloté par des événements → Diagramme d'état (stateDiagram-v2)
├─ Comparaison de 3+ éléments × 2+ dimensions → Tableau
├─ Relations entre composants / niveaux d'architecture → Schéma + Hiérarchie
├─ Définitions / Contexte / Valeurs numériques exactes → Texte (par défaut)
└─ Incertain → Texte par défaut (le diagramme est un plus, pas une décoration)
Bonnes pratiques pour Mermaid :
- Nœuds ≤30 — au-delà, l'algorithme de disposition devient illisible ; découper en plusieurs diagrammes « aperçu → détails »
- Ajouter des étiquettes pour les conditions de branchement et les relations dont le sens n'est pas clair ; pour les flèches de séquence claires, on peut ne pas les étiqueter pour éviter le bruit d'étiquettes
- Utiliser
subgraphpour regrouper les nœuds connexes TD(du haut vers le bas) convient aux hiérarchies ;LR(de gauche à droite) convient aux séquences / pipelines
Conception des tableaux (principes de Tufte) :
- Supprimer les lignes, les fonds et les décorations inutiles — « Above all else show the data »
- Différence minimale efficace : les distinctions visuelles doivent être aussi subtiles que possible mais claires
- Aligner les chiffres par colonne pour faciliter la numérisation et la comparaison
- Le texte doit toujours être horizontal, jamais vertical
Axiome ② : Chaque paragraphe a un but
Déduplication
L'apparition de la même information à plusieurs endroits est l'ennemi numéro un de la maintenabilité — on modifie un endroit et on oublie l'autre.
Critère de détection (une seule condition remplie → nécessite une déduplication) :
- Une même logique/règle apparaît dans 2+ sections → conserver la source faisant autorité (généralement la section sur le modèle de données ou la machine d'état), et remplacer les autres par des références croisées
- Après vérification du comportement, des prérequis, des risques et de la lecture indépendante, les passages ne présentant aucune perte d'information → fusionner ou simplifier
- La documentation répète les détails d'implémentation → juger si le lecteur en a besoin ; conserver les descriptions de comportement et les contrats, ne pas supprimer au motif que le code les contient déjà
- Plusieurs approches équivalentes → donner une recommandation par défaut ; conserver les alternatives nécessaires dont les conditions de compatibilité, de droits ou d'utilisation diffèrent
ARID ≠ DRY : La documentation accepte les répétitions nécessaires — il est raisonnable de reformuler les concepts abordés dans la section de référence au sein d'un tutoriel. Mais éliminer la maintenance parallèle : un même fait ne doit pas être maintenu indépendamment à deux endroits, sinon l'un des deux sera nécessairement obsolète.
Simplification
Supprimer tout ce qui ne sert pas les besoins actuels du lecteur.
| Mauvais signe | Correction | Pourquoi |
|---|---|---|
| Répétition préparatoire : « Dans cette section, nous allons discuter de… » | Fusionner en une formulation directe | Conserver l'indication nécessaire des étapes |
| Mots de remplissage : « Il est à noter que » / « Il est intéressant de mentionner que » | Simplifier les phrases d'introduction | Les avertissements ou limitations eux-mêmes doivent toujours être conservés |
| Voix passive excessive (« est utilisé pour… », « sera… ») | Passer à la voix active SVO | Plus court, plus clair, le lecteur sait « qui fait quoi » |
| Dérive synonymique (même fonction avec des mots différents) | Uniformiser la terminologie, un mot = un sens | Permet au lecteur d'identifier clairement le nom de la fonction |
| Phrases longues et complexes difficiles à lire | Découper les phrases selon la logique | Ne pas briser la relation entre conditions, exceptions et conclusions |
| Énumération de solutions équivalentes | Recommandation en premier, alternatives nécessaires ensuite | Conserver les choix viables sous différentes contraintes |
Exemples judicieux
Les exemples sont l'outil de réponse rapide le plus puissant, mais aussi le type de contenu le plus facilement abusé. Write the Docs écrit intentionnellement « Include (some) examples » — le mot « some » entre parenthèses est une limitation délibérée.
Quand utiliser des exemples :
- Le lecteur a besoin d'une réponse rapide et sautera directement aux exemples (c'est la première réaction de beaucoup de gens)
- Le concept est difficile à comprendre sans exemple concret
- L'exemple illustre un cas d'utilisation fréquent et réel
Quand ne pas utiliser d'exemples :
- Pour démontrer quelque chose d'évident (Microsoft : « Don't illustrate obvious points »)
- Scénarios artificiels qui n'aident pas à la compréhension ; les exemples synthétiques clairement marqués et dont le comportement peut être vérifié peuvent être conservés
- Ajoutés uniquement par souci « d'exhaustivité », sans besoin réel de l'utilisateur
- Il y a déjà assez d'exemples — en ajouter réduit la capacité de numérisation
Bons exemples :
- Ne couvrent que les cas d'utilisation les plus courants, pas d'énumération exhaustive
- Autonomes et exécutables (copier-coller et ça marche)
- Progressifs, du simple au complexe
- Affichent le résultat attendu pour permettre au lecteur de vérifier
- N'omettent le code standard que si l'exemple reste exécutable ou que les prérequis sont clairs ; conserver les importations nécessaires, la gestion des erreurs et la sortie attendue
Mauvais exemples :
- Démontrent quelque chose d'évident
- Scénarios artificiels et irréalistes
- Un exemple tente de couvrir trop de variables
- Intègrent une gestion d'erreur sans rapport avec l'exemple
- Code prétendu exécutable mais non vérifié ; lorsque l'exécution n'est pas possible, marquer clairement les limites de la vérification
Règles de placement :
- Exemple simple d'une ligne → intégré dans le corps du texte
- Exemple plus long → séparé des références denses (paragraphe indépendant ou zone pliable)
- Exemples dans la documentation de référence → rester sobre, ne faire qu'illustrer l'utilisation, ne pas les mélanger avec un enseignement
Référence rapide des métriques quantitatives
Ce qui suit n'est qu'une indication de premier niveau ajustée selon la langue et le lecteur ; voir la liste de vérification pour plus de détails.
| Dimension | Point de départ suggéré | Limite d'utilisation |
|---|---|---|
| Longueur de phrase en anglais | Surveiller les imbrications après environ 20 mots | Ne pas appliquer mécaniquement au chinois, ne pas briser conditions et contrats |
| Paragraphe | Un paragraphe = une idée principale | Les exceptions et avertissements peuvent suivre le paragraphe original |
| Listes/étapes | Envisager un regroupement lorsqu'elles sont longues | Ne pas supprimer d'étapes complètes pour atteindre un certain nombre |
| Voix passive | Réécrire lorsque le sujet est flou | Ne pas fixer de pourcentage à atteindre |
| Mermaid | Envisager un aperçu et des détails lorsque le nombre de nœuds est élevé | Juger en fonction de la lisibilité réelle du rendu |
| Tableau | Envisager de diviser ou de transposer les tableaux larges | Conserver les colonnes et unités nécessaires à la comparaison |
Les chiffres sont des suggestions, pas des normes de l'industrie ou des lois de recherche ; ne pas modifier les faits, les contrats, les textes de sécurité ou juridiques pour atteindre ces chiffres.
Référence rapide des anti-patrons
| Anti-patron | Symptôme | Solution |
|---|---|---|
| Almighty Thud | Document monolithique, toutes les informations de même poids, les décisions clés sont noyées | Diviser ou ajouter une hiérarchie de priorités |
| Mélange des types | Tutoriel contenant une référence API, référence contenant des « pourquoi » | Séparer selon Diátaxis |
| Répétition préparatoire | Phrases d'introduction sans information substantielle | Simplifier la formulation, conserver les risques et les indications d'étapes |
| Dérive synonymique | Même fonction désignée par des mots différents | Uniformiser la terminologie |
| Relation floue | Il faut deviner le sens des branches ou des flèches | Ajouter des étiquettes pour les relations ambiguës |
| chartjunk | Tableaux avec lignes décoratives et fonds inutiles | Supprimer les éléments décoratifs ne transmettant pas d'information |
| Surcharge d'exemples | Exemples exhaustifs pour tous les scénarios | Ne conserver que les cas d'utilisation les plus courants |
| Maintenance parallèle | Même fait maintenu indépendamment à plusieurs endroits | Conserver un seul endroit, remplacer les autres par des liens |