Rédiger des pages courtes qui montrent les usages fréquents d’une commande

## Chercher si la page existe déjà, puis choisir son dossier selon le système Recherchez la commande dans toutes les arborescences de pages sources et traduites avant de créer quoi que ce soit. Si une page existe, modifiez-la au lieu de créer un doublon. Si elle n’existe pas, déterminez où la syntaxe documentée fonctionne réellement. - Placez une commande dans le répertoire commun uniquement lorsque la même syntaxe fonctionne sur au moins deux plateformes. - Placez une commande qui fonctionne sur une seule plateforme dans le répertoire de cette plateforme. - Conservez les pages anglaises dans l’arborescence principale et les traductions dans des arborescences propres à chaque langue, avec le même chemin de plateforme. - Utilisez des noms de fichiers en minuscules, sauf si une règle propre à la plateforme impose la casse canonique de la commande dans le titre de la page ou lors de son appel. Ne choisissez pas un répertoire d’après la réputation ou le nom de la commande. Vérifiez d’abord les plateformes prises en charge et la syntaxe. ## Garder la page courte, avec le titre et la description avant les exemples Rédigez chaque page comme une petite référence Markdown en suivant cet ordre fixe : 1. Un seul titre H1 dont le nom de commande correspond au nom du fichier, sans tenir compte de la casse lorsque le dépôt l’autorise. 2. Une description sous forme de citation, de préférence sur une ou deux lignes. 3. Une ligne obligatoire « Plus d’informations » contenant une URL de la source officielle entre chevrons. 4. Des exemples pratiques, chacun composé d’une description à puce à l’impératif, suivie d’une ligne distincte présentant la commande sous forme de code en ligne. 5. Un saut de ligne à la fin du fichier. Utilisez cinq exemples par défaut et ne dépassez jamais huit exemples. Laissez une ligne vide entre la description et la commande ainsi qu’entre les exemples. N’utilisez ni gras, ni italique, ni mise en forme Markdown décorative dans le contenu de la page. ## Choisir des exemples pour les tâches réelles les plus fréquentes Sélectionnez des exemples qui résolvent les tâches réelles les plus courantes. Rédigez les descriptions à l’impératif : « Répertoriez les fichiers », et non « Répertorie les fichiers ». Gardez-les courtes et axées sur l’action, sans expliquer les concepts généraux du système d’exploitation. Vérifiez chaque exemple dans le manuel de la commande, l’aide intégrée ou la documentation officielle. Respectez l’espacement documenté entre les options et les arguments ; utilisez `--option arg`, sauf si la commande exige explicitement une autre forme. Placez « Afficher l’aide » et « Afficher la version » comme les deux derniers exemples, dans cet ordre, lorsque ces appels existent. Ces exemples sont moins prioritaires : omettez-en un lorsqu’un exemple pratique plus utile est nécessaire et que la limite de la page serait dépassée. ## Signaler par des doubles accolades les parties à remplacer Entourez les valeurs remplaçables de doubles accolades. Utilisez systématiquement les formes sémantiques suivantes : - `{{path/to/file}}`, `{{path/to/directory}}` et `{{filename}}` pour les entrées du système de fichiers ; - `{{file1 file2 ...}}` pour plusieurs arguments ; - `{{option1|option2}}` pour les choix possibles ; - `{{1..5}}` pour les plages numériques et `{{*.ext}}` pour les motifs à caractères génériques ; - `{{[-v|--verbose]}}` pour les options courtes et longues équivalentes ; - `{{[-it|--interactive --tty]}}` pour les indicateurs groupés. Lorsque les formes courte et longue existent toutes les deux, affichez-les toutes les deux. N’inventez jamais de forme courte : les indicateurs de version et les autres options courantes varient selon la commande. N’imbriquez pas les paramètres substituables et ne remplacez pas la syntaxe obligatoire à doubles accolades par des accolades simples ou des crochets. Utilisez des chevrons pour les frappes de touches : `<a>`, `<Enter>`, `<Space>`, `<Ctrl>`, `<Alt>` et `<Shift>`. Écrivez les combinaisons avec une espace, comme `<Ctrl c>`, et les séquences sous forme de groupes adjacents, comme `<Esc><u>`. ## Vérifier que le lien s’ouvre, puis renvoyer au manuel officiel Chaque page doit contenir un lien vers des informations complémentaires. Privilégiez le manuel officiel de la commande, la documentation du projet, un service de pages de manuel maintenu ou la documentation du fournisseur de la plateforme. Avant d’accepter un lien, suivez les redirections et confirmez que la réponse finale est réussie. Ne vous fiez pas à une URL uniquement parce qu’elle semble plausible. Conservez le lien entre chevrons sur la ligne dédiée « Plus d’informations » et évitez les sources promotionnelles ou non officielles lorsqu’une source primaire existe. Utilisez les mêmes sources faisant autorité pour vérifier les noms de commandes, les formes d’options, l’espacement des arguments, le comportement sur chaque plateforme ainsi que la syntaxe de l’aide et de la version. ## Écrire les chemins et les variables comme l’attendent Windows et les autres systèmes Pour les pages de commandes Windows, conservez les noms de fichiers en minuscules, sauf indication contraire de la politique du dépôt, mais respectez la casse canonique de la commande dans le titre H1 et les exemples. Utilisez des barres obliques inverses dans les paramètres de chemin. Écrivez les variables d’environnement avec la syntaxe de l’interpréteur documenté : `%VARIABLE%` pour l’interpréteur de commandes traditionnel et `$Env:VARIABLE` pour PowerShell. Les exemples destinés à PowerShell doivent fonctionner dans la plus ancienne édition prise en charge comme dans l’édition actuelle, sauf si la page déclare une exigence plus restreinte. Sur les autres plateformes, respectez leurs conventions natives en matière de chemins, d’interpréteurs, de variables d’environnement et d’options. Une page commune n’est valide que si la syntaxe de commande présentée est réellement portable. ## Créer des pages pour les autres noms et les sous-commandes d’une commande Créez les pages d’alias avec l’outil prévu à cet effet dans le dépôt, lorsqu’il existe. Indiquez que la commande est un alias, ajoutez un lien vers les informations de la source officielle et fournissez un exemple qui ouvre la page de référence de la commande d’origine. Synchronisez les pages d’alias traduites à l’aide du même outil au lieu de modifier indépendamment leur structure générée. Pour les commandes comportant des sous-commandes, mentionnez dans la description de la page parente les sous-commandes représentatives qui disposent de pages distinctes. Attribuez à chaque sous-commande documentée sa propre page dont le nom est séparé par des traits d’union, et incluez un exemple qui ouvre la référence correspondante. Ne surchargez pas la page parente avec des procédures détaillées de sous-commandes qui appartiennent à leurs propres pages. ## Traduire la page sans changer ses commandes ni sa structure Ne traduisez qu’après la création de la page anglaise. Conservez la même structure d’exemples, le même chemin de plateforme, les mêmes commandes et les mêmes paramètres substituables. Ne modifiez pas les domaines réservés aux exemples et conservez les mots des paramètres dans la langue source lorsque la politique du dépôt l’exige. Appliquez les règles de rédaction propres à chaque langue au lieu de reproduire mécaniquement la grammaire anglaise. Par exemple : - Le chinois sépare le texte latin et les nombres du texte chinois par des espaces et utilise des signes de ponctuation pleine chasse. - Le français emploie la troisième personne dans les descriptions d’exemples et une espace avant les signes de ponctuation qui l’exigent. - L’espagnol emploie des descriptions à la troisième personne et les termes techniques localisés privilégiés. - Le portugais brésilien et le portugais européen emploient des descriptions à la troisième personne. - L’indonésien emploie une forme concise de description des commandes, sans préfixes verbaux superflus. Validez la page traduite avec les mêmes contrôles structurels que la source anglaise. ## Contrôler la page avec l’outil de vérification avant la relecture par une personne Exécutez le linter de pages du dépôt sur le fichier modifié avant de demander une relecture humaine. N’effectuez un lint de l’ensemble de l’arborescence que si la modification ou la politique du dépôt l’exige. Relisez la page pour vérifier : - que le titre et le nom du fichier correspondent ; - que la description sous forme de citation est courte et qu’elle contient un lien d’information valide ; - qu’elle comporte cinq exemples privilégiés et jamais plus de huit ; - que les descriptions sont à l’impératif et que les lignes vides sont correctes ; - que les formes d’options sont vérifiées et que les paramètres substituables utilisent des doubles accolades ; - que le répertoire de plateforme et la syntaxe native sont corrects ; - que les exemples d’aide et de version figurent aux dernières positions lorsqu’ils sont inclus ; - qu’aucune mise en forme décorative n’est présente ; - que les traductions respectent les règles propres à la langue ; - qu’un saut de ligne termine le fichier. Utilisez les scripts de maintenance du dépôt, lorsqu’ils sont disponibles, pour les mises à jour mécaniques des titres, liens, alias, renvois et commandes. Privilégiez le mode dry-run avant toute modification étendue par script. ## Donner à l’IA le manuel et des pages similaires avant la rédaction Réduisez le coût de l’IA et les cycles de correction en fournissant des preuves avant la rédaction. Incluez la sortie de l’aide ou du manuel de la commande, indiquez deux ou trois pages similaires approuvées et fournissez le modèle de page au lieu de demander à l’agent de se souvenir des conventions. Vérifiez d’abord si une page existe déjà. Regroupez les demandes de pages apparentées lorsqu’elles partagent le même contexte, mais relisez chaque page séparément. Rédigez cinq ou six exemples à forte valeur ajoutée au lieu de remplir la limite de huit exemples. Exécutez le linter avant la relecture humaine afin que les erreurs de formatage ne mobilisent pas l’attention de la personne chargée de la relecture. Les économies doivent provenir de meilleures entrées, de la réutilisation et d’une validation déterministe, jamais de l’omission de la vérification des sources ni d’une baisse de la qualité de la page.