Rédiger une documentation technique en reStructuredText avec de vrais exemples et vérifier la compilation

## Expliquer ce dont le lecteur a besoin et laisser les détails internes au code Écrivez pour les personnes qui doivent comprendre et utiliser le comportement documenté. Expliquez les concepts aussi clairement et brièvement que possible. Incluez des détails de bas niveau lorsqu’ils aident le lecteur à prendre une décision, mais laissez au code source les aspects internes très profonds de l’implémentation. - Décrivez la signature d’une méthode uniquement lorsqu’elle est essentielle à la bonne utilisation de cette méthode. - Documentez les arguments et les options de commande qui influencent le flux de travail principal, pas tous les commutateurs disponibles. - Ne répétez pas l’explication d’une erreur ou d’une exception lorsque son message dans le code indique déjà clairement la cause et la solution. - Préférez une explication ciblée, un exemple réaliste et un lien vers des détails connexes à un catalogue exhaustif. ## Choisir la branche selon le type de modification et les données de version N’inscrivez jamais en dur la liste des versions maintenues. Consultez les métadonnées de publication faisant autorité pour le projet avant de choisir une branche cible, puis appliquez systématiquement les règles correspondant au type de modification. - Les corrections de bogues ciblent la branche maintenue la plus ancienne qui contient le bogue. - La documentation d’une nouvelle fonctionnalité cible la branche qui a introduit cette fonctionnalité. Si cette branche n’est plus maintenue, utilisez la branche maintenue suivante. - Les fautes de frappe, reformulations, restructurations et autres modifications non fonctionnelles ciblent la branche maintenue la plus ancienne. - La documentation des sous-projets gérés selon une version indépendante suit leur propre politique déclarée. Lorsque cette politique le précise, dirigez toutes les modifications vers la branche maintenue la plus ancienne, y compris les nouvelles fonctionnalités. Consignez le type de modification et les données de maintenance utilisées pour prendre la décision. Si les métadonnées de publication sont indisponibles ou ambiguës, ne devinez pas la branche. ## Garder les mêmes signes de titre et la même largeur de ligne Utilisez systématiquement les caractères de soulignement associés aux niveaux de titre : signes égal pour le niveau 1, traits d’union pour le niveau 2, tildes pour le niveau 3, points pour le niveau 4 et guillemets doubles pour le niveau 5. Chaque soulignement doit couvrir toute la longueur du texte du titre. Appliquez toute exception propre à un chemin déclarée par le dépôt. Coupez le texte à 80 caractères, sauf pour les tableaux, les URL et les lignes isolées lorsqu’une coupure réduirait la lisibilité. Placez les puces de liste au début de la ligne. Ne répartissez pas une portion en gras ou en italique sur plusieurs lignes. Pour le code en ligne, utilisez des paires de doubles accents graves. Pour les exemples de code dans le langage par défaut, utilisez la forme concise à double deux-points, sauf si le marqueur devait se retrouver seul sur sa ligne. Utilisez une directive code-block explicite lorsque le langage ou le contexte de rendu doit être indiqué. ## Uniformiser le retrait des directives et l’écriture des liens Indentez le contenu des directives de quatre espaces. Laissez une ligne vide après un marqueur à double deux-points et avant son contenu, ainsi qu’avant et après chaque directive. Alignez les lignes de continuation d’un élément de liste multiligne sur le début du texte de cet élément. Utilisez la directive d’admonition standard correspondant au message : note, tip, warning, caution ou seealso. Pour les ajouts de version et les éléments obsolètes, utilisez les directives dédiées avec la version concernée et une courte explication. Utilisez des chemins de document absolus pour les liens internes. Pour créer un lien vers une section précise, utilisez une référence croisée munie d’une étiquette. N’utilisez jamais de chemin interne relatif. Pour les sites externes, placez les cibles de liens nommées à la fin du fichier au lieu d’intégrer des URL directement dans le texte. Utilisez les rôles dédiés du système de documentation pour les classes, méthodes, fonctions et types intégrés de l’API du langage. ## Présenter les exemples de configuration YAML, XML et autres toujours dans le même ordre Lorsqu’une fonctionnalité accepte plusieurs formats de configuration, montrez tous les formats pris en charge dans une directive configuration-block. Conservez le même ordre dans l’ensemble du dépôt afin que les lecteurs puissent comparer les pages sans devoir réapprendre leur disposition. - Pour les services et la configuration générale, utilisez YAML, XML, puis le format du langage de programmation. - Pour le routage, la validation et la correspondance d’objets, utilisez les attributs, YAML, XML, puis le format du langage de programmation. - Pour les ressources de traduction, utilisez XML, YAML, puis le format du langage de programmation. Utilisez des onglets ordinaires uniquement pour du contenu parallèle qui n’est pas de la configuration, comme des outils ou flux de travail alternatifs. Lorsque les exemples diffèrent entre les applications intégrées au framework et les applications autonomes, utilisez des identifiants de langage distincts afin que le système de rendu et le lecteur puissent distinguer les contextes. ## Écrire des exemples de code avec des noms réalistes et un commentaire de nom de fichier Respectez les normes de codage du langage cible et les bonnes pratiques établies du projet. Utilisez des noms et des situations réalistes plutôt que des mots de substitution qui masquent l’intention. Employez les domaines réservés aux exemples et le nom de fournisseur d’exemple adopté par le dépôt. - Coupez les lignes des blocs de code à 85 caractères lorsque cela reste pratique. - Indentez les exemples de quatre espaces, y compris en YAML. - Incluez les déclarations d’espace de noms et d’import lorsqu’elles facilitent l’exécution de l’exemple ou la compréhension des types. - Commencez un bloc de code par un commentaire indiquant le nom du fichier. N’ajoutez pas de ligne vide, sauf si la ligne suivante est également un commentaire. - Préfixez chaque commande de l’interpréteur par un symbole d’invite. - Utilisez la forme de commentaire propre au langage lorsque vous repliez des blocs omis. - Utilisez de simples points de suspension, sans marqueur de commentaire, lorsque vous raccourcissez une partie d’une valeur sur la même ligne. - Respectez les règles d’espacement propres au format, notamment les espaces dans les correspondances YAML en ligne lorsqu’ils sont requis. Un exemple doit enseigner la voie prise en charge sans prétendre constituer une implémentation complète pour la production. N’omettez pas un prérequis dont l’absence ferait échouer le code présenté. ## Écrire en anglais américain simple et éviter des mots comme « simply » Écrivez en anglais américain. Utilisez la casse de titre pour les titres de section : mettez une majuscule initiale au premier et au dernier mot ainsi qu’aux mots principaux, et laissez les mots fonctionnels courts en minuscules, sauf lorsqu’ils commencent le titre. Adressez-vous au lecteur avec « you » au lieu de parler en tant que « we ». Utilisez des pronoms neutres. Préférez la voix active, un vocabulaire simple et des phrases directes adaptées à un public international. Les contractions sont autorisées. N’utilisez pas la virgule d’Oxford. Évitez les expressions idiomatiques et les mots condescendants comme « obviously », « simply », « just », « easy », « clearly », « trivial » et « of course ». Ces mots peuvent masquer une explication insuffisante et décourager le lecteur. Chaque image nécessite un texte de remplacement concis qui commence par une majuscule et se termine par un point. Ne commencez pas par « A screenshot of » ou « Diagram of ». Expliquez les diagrammes complexes dans le texte environnant au lieu de forcer tous les détails dans le texte de remplacement. ## Avant de finir, compiler la documentation et vérifier avertissements et liens cassés Écrivez les répertoires avec une barre oblique finale et les extensions de fichier avec un point initial. Utilisez une racine de projet d’exemple neutre, telle que `your-project/`, dans les arborescences de répertoires. Maintenez la cohérence des noms de fichiers, chemins, commandes et cibles de référence entre le texte et les exemples. Avant de considérer une modification de documentation comme terminée : 1. Installez les dépendances de compilation de la documentation dans l’espace de travail de compilation désigné. 2. Exécutez la commande de compilation documentée par le dépôt. 3. Mettez temporairement le résultat généré à disposition lorsqu’une inspection visuelle est nécessaire. 4. Vérifiez dans les pages modifiées les avertissements, références rompues, directives mal formées, le rendu du code, la hiérarchie des titres et les descriptions d’images. 5. Confirmez que la branche cible choisie correspond toujours au type de modification et aux métadonnées de maintenance actuelles. Ne signalez pas de réussite sur la seule base de l’inspection du code source lorsque le dépôt fournit un mécanisme de compilation de la documentation.