CommunityRédaction et éditiongithub.com

jakubkrehel/better-writing

Améliore la rédaction des contenus produits dans votre projet.

Qu'est-ce que better-writing ?

Cette compétence est conçue pour les agents d'IA et les développeurs qui souhaitent améliorer la qualité et la cohérence de la copie produit (textes d'interface, messages d'erreur, libellés). Elle fournit un ensemble de principes rédactionnels éprouvés, basés sur la clarté, la simplicité et l'accessibilité. Elle prend en charge tous les environnements où le texte est présenté à l'utilisateur (web, mobile, CLI) et s'appuie sur le fichier SKILL.md comme guide de style. En pratique, l'agent utilise ces règles pour relire, corriger ou rédiger du nouveau contenu, en s'assurant que la voix du produit reste cohérente, que les libellés des boutons sont orientés action, que les messages d'erreur indiquent comment résoudre le problème, et que les liens décrivent leur destination. Chaque recommandation est classée par sévérité (HIGH, MEDIUM, LOW) et suit un format de rapport standardisé. L'objectif est d'éliminer les ambiguïtés, les formulations alambiquées et les incohérences terminologiques, afin d'offrir une expérience utilisateur plus fluide et plus professionnelle.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jakubkrehel/skills/tree/main/skills/better-writing

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

Rédaction d'interface

Clair et concis l'emporte sur l'ingéniosité ; cohérent l'emporte sur varié. Le meilleur message d'erreur est l'interaction repensée pour que l'erreur ne puisse pas se produire.

La façon dont la copie est rendue (capitalisation via text-transform, troncature, ponctuation intelligente) relève de better-typography. Le balisage des erreurs et les annonces (aria-invalid, régions live) relèvent de better-accessibility. L'espace réservé aux chaînes traduites relève de better-layout.

Reconnaître la voix existante

Avant d'écrire ou de relire, lisez la copie environnante. Notez la terminologie du produit, ses conventions de localisation et tout guide de style vocal ou de contenu.

Une voix de marque délibérée n'est pas un défaut. Ne signalez un écart par rapport au langage clair que lorsqu'il crée une incohérence, une ambiguïté, un risque de traduction ou un ton que les enjeux ne justifient pas.

Une voix, un ton flexible

Le produit a une seule voix et sa copie existante l'établit. Une modification locale n'a pas le droit d'en inventer une nouvelle. Gardez les termes cohérents : si c'est « Archiver » dans le menu, ce n'est pas « Déplacer vers le stockage » dans le toast. Le ton s'adapte aux enjeux :

ContexteTon
Succès, intégration, états videsChaleureux, peut être léger
Actions courantes, paramètresNeutre, minimal
Erreurs, confirmations destructricesCalme, simple, zéro jeu
Perte de données, sécuritéSérieux, explicite

S'adresser directement au lecteur

Dans la copie instructive, écrivez « vous », pas « l'utilisateur ». Dans les erreurs, « nous » invite à l'ambiguïté et semble être une dérobade, alors préférez « Impossible de charger le contenu » à « Nous rencontrons des difficultés pour charger ce contenu ». Une première personne établie peut rester dans la copie à faible enjeu où elle reste claire.

Utilisez les possessifs avec parcimonie : « Favoris » est préférable à « Vos favoris ». Maintenez une perspective tout au long d'un flux.

Des mots simples plutôt que des jeux de mots

Choisissez des mots qu'un lecteur fatigué comprend du premier coup, et supprimez chaque mot qui ne sert à rien. Pas d'idiomes, pas de familiarités, pas d'humour qui ne se traduira pas.

Évitez le genre inutile : « Les abonnés peuvent publier des recettes », pas « chaque abonné peut publier ses propres recettes ». Adaptez-vous au périphérique de saisie : « appuyer » sur le tactile, « cliquer » avec une souris, « sélectionner » lorsque les deux sont possibles.

Ne construisez jamais une phrase à partir de fragments autour d'une variable ("Vous avez " + n + " nouveaux messages"), car l'ordre des mots change selon la langue. Utilisez une chaîne modèle complète avec une pluralisation appropriée.

Boutons orientés verbe

Un libellé de bouton commence par un verbe nommant l'action : « Envoyer », « Enregistrer le brouillon », « Supprimer le projet ». Jamais « OK ! », « C'est parti ! » ou un simple « Oui » et « Non » sur une action conséquente.

Un bouton de confirmation répète la conséquence, afin que la boîte de dialogue puisse être répondue sans lire le corps. « Supprimer ce projet ? » propose Supprimer le projet et Annuler.

Vocabulaire cohérent dans les flux en plusieurs étapes

Un flux en plusieurs étapes utilise un seul vocabulaire du début à la fin : « Commencer » pour entrer, « Continuer » ou « Suivant » (choisir un) pour avancer, « Terminé » pour finir. Alterner les synonymes fait se demander aux utilisateurs si les boutons font des choses différentes.

Les liens décrivent leur destination

Le texte du lien doit avoir un sens hors contexte, car les utilisateurs de lecteurs d'écran naviguent par une liste des liens de la page. Écrivez « Lire la documentation de facturation ». « Cliquez ici » échoue à cette règle et à la règle du verbe de périphérique en même temps.

Un simple « En savoir plus » pose problème dès que deux apparaissent sur une même page. Suffixez chacun : « En savoir plus sur les exportations ».

Une politique de capitalisation unique

Choisissez la casse titre ou la casse phrase par type d'élément, puis appliquez-la à chaque instance de ce type. La casse phrase est la valeur par défaut la plus sûre. Elle est plus calme, n'a pas de règles par mot à retenir et se localise proprement. « Enregistrer les modifications » à côté de « Ignorer les modifications » semble bâclé.

Les paramètres décrivent l'état ACTIVÉ

Libellez un interrupteur pour ce qui se produit lorsqu'il est activé. « Envoyer les accusés de réception » permet aux utilisateurs de déduire l'état désactivé ; la forme négative (« Ne pas envoyer les accusés de réception ») transforme l'interrupteur en double négation.

Créez un lien direct vers un paramètre référencé plutôt que de décrire le chemin pour y accéder : un lien « Paramètres de notification », pas « Aller dans Paramètres > Notifications > E-mail ».

Les erreurs disent comment corriger, à côté de ce qui a échoué

Une erreur est une instruction et elle doit se trouver à côté du champ qui a échoué :

MauvaisBon
Ce mot de passe est trop courtChoisissez un mot de passe d'au moins 8 caractères
Nom invalideUtilisez uniquement des lettres pour votre nom
Oups ! Une erreur s'est produite.Impossible d'enregistrer. Vérifiez votre connexion et réessayez.

Pas de blâme, pas de « oups », pas de points d'exclamation. Formulez les indices de manière positive (« Utilisez uniquement des lettres », pas « N'utilisez pas de chiffres ou de symboles ») et montrez-les avant l'erreur, pas après. Lorsque la même erreur se reproduit, repensez l'interaction au lieu de reformuler le texte.

Les états vides indiquent la voie à suivre

Un état vide indique ce qu'est cet endroit, comment le remplir et propose une action claire :

<!-- Mauvais : une absence de réaction -->
<p>Aucun résultat.</p>

<!-- Bon : orientation plus une prochaine étape -->
<p class="font-medium">Aucun projet pour l'instant</p>
<p class="text-sm text-zinc-500">Les projets rassemblent vos tâches et fichiers.</p>
<button class="mt-4">Créer un projet</button>

Un état vide de recherche ou de filtre nomme la requête et propose une sortie : « Aucun résultat pour 'trimestriel'. Effacer les filtres ». Ne placez jamais d'informations persistantes dans un état vide. Elles disparaissent dès que du contenu existe.

Les espaces réservés sont des exemples, pas des libellés

Un espace réservé montre le format attendu : [email protected], JJ/MM/AAAA. Il disparaît lors de la saisie, donc il n'est jamais le seul libellé. Chaque champ conserve un libellé visible.

Rapports

Sévérité. HIGH induit l'utilisateur en erreur ou cache comment se remettre d'une erreur. MEDIUM brise la cohérence de la voix, de la terminologie ou de la capitalisation. LOW est un polissage de formulation isolé.

Vérification. La source seule suffit ici. Vérifiez chaque libellé par rapport à l'action qu'il invoque, chaque erreur pour une correction indiquée et la terminologie par rapport à la copie environnante. Aucune vérification de navigateur n'est requise.

Format. Regroupez les constatations sous le principe qu'elles violent, ordonnées par sévérité, une ligne par cause racine listant chaque emplacement où elle apparaît :

SévéritéEmplacementAvantAprèsPourquoi

Emplacement est chemin/vers/fichier:ligne. Pourquoi nomme le principe et l'impact utilisateur.

Terminez par Bloquer lorsqu'il reste des HIGH, Approuver sinon, en laissant le reste dans le tableau comme travail à faire. N'approuvez jamais une couverture que vous n'avez pas inspectée. S'il n'y a rien à signaler, indiquez « Aucune constatation rédactionnelle exploitable » et rapportez la vérification.

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

Skills associés