CommunityRédaction et éditiongithub.com

Rédaction sobre

Rédigez, modifiez ou révisez des documentations, README, commentaires de code, changelogs, PR et messages de commit pour qu'ils soient clairs, concis et factuels. Idéal pour toute écriture technique ou nettoyage de texte IA.

Qu'est-ce que Rédaction sobre ?

Ce skill, 'Rédaction sobre', est conçu pour les développeurs et les agents d'IA qui produisent ou nettoient du contenu technique. Il s'applique à une large gamme de sorties : documentation, README, commentaires de code, changelogs, PRs et messages de commit. L'objectif principal est de garantir que tout écrit soit compréhensible dès la première lecture par un ingénieur fatigué, sans perdre un seul fait. Le skill offre trois modes d'intervention : écriture (création à partir de zéro), édition (révision minimale pour corriger les défauts tout en préservant le bon travail) et révision (audit sans réécriture, listant les problèmes avec la règle violée et une solution). Il fonctionne sur n'importe quelle plateforme (Claude, Cursor, Codex, etc.) et s'appuie sur un ensemble de règles strictes: ne jamais rien inventer (les exemples, nombres, benchmarks doivent provenir de la source), protéger le texte exact (code, commandes, chemins), utiliser les vrais noms de symboles, et garder toute information factuelle (nombres, noms, commandes) avec ses qualificatifs précis comme 'généralement' ou 'environ'. La structure du document doit suivre un mode unique (Diátaxis) : tutoriel, procédure, référence ou explication, et chaque phrase doit être directe et concise, en évitant tout jargon inutile, emphase artificielle ou contenu promotionnel. Le skill aide à produire un contenu technique de haute qualité, factuel et lisible, en évitant les pièges courants de l'écriture technique.

Compatible avec~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/John-UNOwen/dsh-doc-guard/tree/main/skills/plain-docs

Installed? Explore more Rédaction et édition skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait Rédaction sobre ?

Écrivez pour qu'un ingénieur fatigué comprenne du premier coup. Gardez chaque fait. N'inventez rien. Supprimez tout mot qui ne fait aucun travail.

Choisissez la tâche

  • Écrire. Construire un nouveau document à partir de code, notes ou d'une demande.
  • Modifier. Corriger un brouillon, souvent rédigé par une IA. Faites la plus petite modification qui le corrige et laissez les bonnes phrases tranquilles. Modifiez uniquement la partie que l'on vous a demandé de modifier. Ne remballez pas, ne renumérotez pas et ne reformatez pas les lignes que vous ne changez pas. Si plus de la moitié des phrases environ ont besoin de travail, ou si le brouillon est dans le mauvais mode, reconstruisez-le à partir de la liste des faits (règle 1) au lieu de le rapiécer. Si l'utilisateur a rédigé le brouillon lui-même, proposez la reconstruction et attendez un oui.
  • Réviser. Lorsqu'on vous demande d'auditer ou de signaler sans réécrire, listez chaque problème comme la ligne citée, la règle qu'elle enfreint et une correction en quelques mots. Ordonnez les constats : les faits erronés ou non étayés en premier, puis les ambiguïtés et les étapes manquantes, puis le remplissage, puis le style. Ne changez rien. Si le texte est propre, dites-le.

Sachez ce qui prime

  1. L'instruction de l'utilisateur pour cette tâche.
  2. Le guide de style du projet et les documents déjà dans le dépôt : leurs termes, style de titre, style de citation, retour à la ligne et disposition des fichiers. Correspondance avec eux, même s'ils diffèrent des mécanismes ci-dessous.
  3. Cette compétence.

Les chaînes de caractères d'interface utilisateur du produit, les pages marketing et les textes juridiques suivent leurs propres directives. Ne les restylez pas avec cette compétence.

Règles qui remplacent le reste

  1. Gardez chaque fait à sa force. Avant de modifier, listez pour vous-même chaque nombre, nom, commande, indicateur, valeur par défaut, limite, condition, mise en garde et lien, chacun avec son qualificatif (« généralement », « environ », « peut », « uniquement sous Linux »). La liste doit survivre. « Peut réduire » ne devient jamais « réduit », et un plan ne devient jamais une promesse. Si le brouillon est en désaccord avec le code, ou avec lui-même, signalez le conflit. Ne prenez pas parti en silence.
  2. N'inventez rien. N'ajoutez aucun exemple, nombre, benchmark, raison ou comportement que la source ne prend pas en charge. Lorsque vous écrivez à partir du code, lisez le code et énoncez uniquement ce qu'il fait. Vérifiez chaque commande, indicateur, option, chemin et lien par rapport au code, à la sortie --help ou à l'arborescence des fichiers avant de l'écrire. Ne devinez pas le comportement avec « semble » ou « probablement ». Lorsqu'une phrase a besoin d'un détail que vous n'avez pas, écrivez [BESOIN : ce qui manque] à sa place. Si les lacunes laisseraient le document vide et que l'utilisateur peut répondre, posez jusqu'à cinq questions courtes en un tour avant d'écrire. Si personne n'est là pour répondre, utilisez les indicateurs.
  3. Protégez le texte exact. Le code, les commandes, les chemins, les indicateurs, les identifiants, les clés de configuration, les messages d'erreur et les citations restent caractère pour caractère. Signalez un problème à l'intérieur d'eux au lieu de les réécrire. Les commentaires et les docstrings dans le code sont de la prose, pas du texte protégé, donc chaque règle ici s'applique à eux. La seule exception : le vrai nom d'utilisateur de l'ordinateur n'apparaît jamais dans les documents ou les messages de commit. Remplacez-le par un espace réservé tel que C:\Utilisateurs\<nom_utilisateur>\ ou /home/<utilisateur>/.
  4. La base de code est la liste de mots. Écrivez le vrai symbole, fichier, indicateur ou nom de commande, pas un synonyme ou une description de celui-ci.
  5. Lorsqu'une règle empire une phrase, corrigez la phrase d'une autre manière ou laissez-la. Une phrase qui obéit à toutes les règles et qui sonne encore mécanique a échoué. Un texte propre ne reçoit aucune modification.

Choisissez d'abord le mode

Nommez d'abord le lecteur : qui il est, ce qu'il sait déjà et ce qu'il est venu faire.

Un document a un seul mode (Diátaxis). Choisissez-le en vous demandant si le lecteur doit agir ou comprendre, et s'il apprend ou travaille.

  • Tutoriel (agir, apprendre). Dites ce que le lecteur va construire. Chaque étape donne un résultat visible, alors montrez la sortie attendue. L'explication se réduit à une clause et un lien. Utilisez « nous » pour le travail que vous et le lecteur faites ensemble (« Maintenant nous ajoutons une route »), et donnez chaque étape comme une commande : « D'abord, exécutez x. Maintenant, ouvrez y. »
  • Procédure (agir, travailler). Résolvez un problème que le lecteur a et supposez la compétence. Donnez uniquement les étapes, avec des embranchements si nécessaire (« Si vous utilisez Docker, passez à l'étape 4 »). Titrez par la tâche : « Faire pivoter la clé API ».
  • Référence (comprendre, travailler). Décrivez les faits, options, valeurs par défaut, limites et erreurs. Laissez de côté les instructions, la persuasion et les précautions. Reflétez la structure de la chose décrite et générez-la à partir du code lorsque vous le pouvez.
  • Explication (comprendre, apprendre). Couvrez un sujet délimité et son pourquoi : décisions de conception, contraintes, alternatives. C'est le seul mode où un point de vue a sa place, et seulement un point de vue que la source ou l'utilisateur détient.

Ne mélangez pas les modes. Divisez le document et liez les parties.

Les autres types de documents suivent le mode le plus proche :

  • README. La seule page qui mélange les modes, alors gardez chaque partie courte : ce qu'est le projet en une ou deux phrases, ce dont il a besoin, comment l'installer et l'exécuter, un exemple fonctionnel minimal, puis des liens vers le reste. Supprimez les sections qui n'ont rien de spécifique à ce projet, comme un texte de contribution générique ou une liste de fonctionnalités qui répète l'introduction.
  • Runbook ou page de dépannage. Une procédure. Pour le dépannage, donnez le symptôme tel que le lecteur le voit (le texte d'erreur exact), puis la cause, puis la correction.
  • Référence API, CLI ou de configuration, et docstrings. Référence.
  • Document de conception, RFC ou enregistrement de décision. Explication. Énoncez d'abord la décision ou la proposition, puis le contexte, les alternatives et ce que chacune coûte.
  • Changelog ou note de version. Dites ce qui a changé, qui cela affecte et ce qu'ils doivent faire. Mettez les changements cassants et les étapes de migration en premier. Écrivez du côté de l'utilisateur (« Les exportations PDF affichent désormais les symboles monétaires »), pas de l'implémentation.
  • Rapport de bug ou problème. Étapes pour reproduire, ce que vous attendiez, ce qui s'est passé, ainsi que les versions et l'environnement.

Organisez la page pour le lecteur

  • Les titres portent le point, en casse de phrase : « Faites pivoter les clés avant leur expiration », pas « Rotation des clés » ou « Aperçu ». Un titre de tâche est un syntagme verbal. Un titre de référence peut nommer la chose : --write, « Codes de sortie ». Utilisez un h1 et ne sautez pas de niveaux.
  • Ne mettez pas de titre sur une section d'une ou deux phrases, sauf dans la référence, où chaque entrée a son propre titre. Ne mettez pas une phrase d'échauffement sous un titre qui la répète.
  • Avant de renommer un titre, recherchez les liens vers son ancre et mettez-les à jour.
  • Commencez par ce que le lecteur est venu chercher : la réponse, la commande, la décision. Le contexte va après ou derrière un lien.
  • Mettez les prérequis avant l'étape 1 : versions, système d'exploitation, autorisations et outils.
  • Utilisez des listes numérotées pour les séquences et des puces pour les éléments à parcourir ou comparer. Introduisez chaque liste par une phrase complète et gardez les éléments parallèles. Utilisez des listes pour les étapes, options, paramètres et changelogs. Utilisez la prose lorsque les éléments construisent un seul argument.
  • Supprimez les étiquettes en gras qui répètent leur ligne (« Performance : Performance améliorée... »). Une amorce en gras est acceptable lorsqu'elle nomme l'élément et que de nouveaux détails suivent. Ne mettez pas en gras les phrases pour insister.
  • Utilisez le nombre réel d'éléments. Ne gonflez pas une liste à trois et n'annoncez pas le décompte (« Trois choses ont changé : »).
  • Décrivez le code tel qu'il est, pas le changement qui l'a produit. « Cette fonction a été ajoutée pour remplacer l'ancienne boucle » est de l'historique. Dites ce que la fonction fait. L'historique appartient aux changelogs, notes de version, guides de migration, enregistrements de décision et messages de commit.
  • N'écrivez pas « nouveau », « récemment », « actuellement », « bientôt » ou « dernier » en dehors des notes de version. Ils deviennent obsolètes. Donnez la version ou la date (2026-11-16).
  • Donnez des valeurs exactes avec des unités : « 30 secondes », pas « un court délai d'attente ».
  • Définissez un terme ou un acronyme spécifique au projet une fois, là où il apparaît pour la première fois.
  • Utilisez un avertissement uniquement pour la perte de données, la sécurité ou une étape irréversible. Mettez-le avant l'étape.
  • Un décompte, une liste ou une arborescence de fichiers que vous énoncez à propos du dépôt doit être vrai au commit qui l'atterrit. Donnez la commande qui le régénère, lorsqu'il y en a une.
  • Utilisez des tableaux pour les éléments comparés sur les mêmes attributs. Mettez le code en police de code. Utilisez le gras pour les étiquettes d'interface utilisateur.
  • Ne mettez pas d'emoji dans les titres ou les puces. Ne terminez pas par une section qui reformule le document ou par une signature joyeuse (« Bon codage ! »). Terminez sur la dernière étape, le dernier fait ou le dernier lien.

Faites fonctionner les exemples

  • Chaque bloc de code s'exécute tel qu'écrit, ou indique quoi remplacer. Marquez un espace réservé comme <nom-du-seau> et dites ce qui va là.
  • Donnez à chaque bloc délimité une balise de langage. Gardez une commande et sa sortie dans des blocs séparés. Laissez l'invite $ hors des commandes pour que le lecteur puisse les copier.
  • Montrez la sortie attendue pour toute étape que le lecteur peut vérifier.
  • Préférez un exemple minimal à trois variations. Utilisez des valeurs réalistes, pas foo et bar.
  • Si vous n'avez pas pu exécuter un exemple, dites-le dans votre réponse, pas dans le document.

Écrivez des phrases qui se lisent une fois

  • Parlez au lecteur comme « vous », au présent. Les tutoriels sont la seule exception : ils peuvent utiliser « nous », comme décrit sous le mode tutoriel. Utilisez « fera » uniquement pour ce qui se passe plus tard.
  • Écrivez les instructions comme des commandes : « Exécutez make test. » Pas « Vous devriez exécuter » ou « Les tests devraient être exécutés ». Mettez la condition en premier (« Pour vider le cache, exécutez x »), un avertissement avant l'étape qu'il protège et le cas courant avant les exceptions.
  • Nommez qui fait quoi : « le compilateur rejette la requête », pas « la requête est rejetée ». Le passif est acceptable lorsque l'acteur est inconnu ou n'a pas d'importance.
  • Donnez à chaque phrase une instruction, ou une idée en dehors des procédures. Divisez les instructions sur environ 20 mots et les autres phrases sur environ 25. Gardez une longue phrase qui porte une idée avec sa condition.
  • Écrivez des phrases entières avec leurs articles et verbes. « Analyseur rejette date erronée → sortie 2, pas d'écriture » devient « L'analyseur rejette une date erronée, se termine avec le code 2 et n'écrit rien. » Épelez les flèches et les raccourcis en prose.
  • Laissez la longueur suivre le contenu. Ne coupez pas les phrases en fragments pour le rythme et fusionnez les phrases courtes lorsque le texte devient saccadé. Ne commencez pas plusieurs phrases à la suite par les mêmes mots. Les étapes et les éléments de liste parallèles sont exemptés.
  • Faites pointer chaque « il », « ceci » et « ils » vers un nom évident, et répétez le nom en cas de doute. N'utilisez jamais « ceci » ou « qui » pour pointer vers une clause entière.
  • Gardez « seulement » et « pas » à côté du mot qu'ils modifient. Brisez les piles de noms : « le script de vérification du budget d'importation de proto » devient « le script qui vérifie le budget d'importation de proto ».
  • Appelez chaque chose par un seul nom partout et utilisez un verbe par action. Ne faites pas pivoter les synonymes pour la variété.
  • Utilisez le mot simple : utiliser, aider, démarrer, montrer, donc, pouvoir. Pas utiliser, tirer parti, faciliter, initier, démontrer, ainsi, avoir la capacité de. Utilisez le verbe, pas un nom fabriqué à partir de lui : « configurer », pas « effectuer la configuration de ». Dites « est » et « a », pas « sert de », « agit comme », « se targue de » ou « propose ».
  • N'écrivez jamais « simplement », « facile », « juste » ou « rapidement » dans une procédure. Si c'était simple, le lecteur ne serait pas là. Laissez « s'il vous plaît » hors des instructions.
  • Des contractions comme « don't » et « it's » sont acceptables. N'utilisez pas de barres obliques pour « ou », de pluriels « (s) » ou de « etc. » (dites clairement qu'une liste est partielle). Évitez les expressions idiomatiques et les abréviations latines.
  • Sonnez comme un collègue qui connaît le système : simple et direct. N'ajoutez pas de personnalité que la source n'a pas, comme des blagues, « Honnêtement, » ou des histoires à la première personne.
  • Faites en sorte que le texte du lien nomme où le lien mène. N'écrivez jamais « cliquez ici ».

Supprimez ce qui ajoute des mots mais pas d'informations

Testez une phrase suspecte en la supprimant. Si le lecteur ne perd rien, laissez-la supprimée.

Emphase artificielle.

  • Contraste avec une affirmation que personne n'a faite : « Ce n'est pas X, c'est Y », « non seulement X mais Y », « Pas de configuration. Pas de configuration. Juste des résultats. » Énoncez Y.
  • Lignes « deux points révèlent » et « faites une pause et pointez » : « La meilleure partie : il met en cache. », « Voici le truc : », « C'est parti. » Le point devrait être la phrase suivante.
  • Slogans et lignes d'accroche : « Moins de configuration. Plus de livraison. », « ça marche », « piles incluses », « zéro configuration ». Dites le comportement ou supprimez la ligne.
  • Questions rhétoriques auxquelles la phrase suivante répond.

Faire le travail du lecteur.

  • Dire au lecteur quoi remarquer ou à quel point c'est important : « Notez que », « Il est important de noter », « Comme vous pouvez le voir », « C'est la partie clé », « Notamment », « Important », « Intéressant ».
  • Épeler ce que les faits disent déjà : « Cela signifie que... », « En d'autres termes... », et les clauses en -ant comme « , assurant la fiabilité » ou « , mettant en évidence la flexibilité de l'API ».
  • Annoncer ce que le document s'apprête à faire : « Dans ce guide, nous explorerons... », « Maintenant, regardons... ». Un énoncé de portée d'une ligne en haut d'un long document est acceptable, tout comme un jalon par grande section.
  • Récapitulations : « En résumé », « Dans l'ensemble », « Pour résumer ».
  • Transitions de remplissage au début d'une phrase : De plus, En outre, Par ailleurs, Cela dit. Utilisez « et », « mais », « donc », « aussi » ou rien.
  • Définir des mots que le lecteur connaît déjà.

Gonflement.

  • Adjectifs sans fondement : puissant, transparent, robuste, complet, flexible, efficace, évolutif, léger. Attachez le nombre, la limite ou le mécanisme que la source donne, ou supprimez l'adjectif.
  • Intensificateurs : très, vraiment, extrêmement, hautement, significativement, grandement, facilement. Donnez le nombre mesuré ou supprimez le mot.
  • Adjectifs en trois par réflexe : « rapide, simple et fiable ». Gardez ceux que la source prend en charge.
  • Affirmations d'importance : crucial, capital, révolutionnaire, un témoignage de, joue un rôle vital.
  • Vocabulaire IA : plonger, tapisserie, paysage, royaume, complexe, multiforme, souligner, mettre en valeur, favoriser, recueillir, améliorer, élever, responsabiliser, débloquer, rationaliser, booster, exploiter, naviguer (figuratif), en constante évolution, de pointe, primordial, myriade, pléthore.
  • Métaphores nominales qui se font passer pour des termes techniques : substrat, surface (comme dans « surface API »), primitive (comme nom), vecteur (signifiant « manière »), coin, lieu, nexus, fondement, échafaudage, étoile polaire, volant d'inertie, paradigme, modalité, fin de partie, cliquet. Choisissez le mot concret.
  • Fausses gammes : « tout, de la journalisation au déploiement », où les deux extrémités ne sont pas sur une seule échelle. Listez les choses.
  • Autorité vague : « les experts recommandent », « la meilleure pratique est », « de nombreuses équipes trouvent ». Nommez la source ou supprimez l'affirmation.
  • Sentiments là où un mécanisme appartient : « la base de données reste à portée de main », « les types qui... »

…

[tronqué pour la traduction]

Skills associés