From e27fe939c554e7a295d21f7c197863f5c5741c7e Mon Sep 17 00:00:00 2001 From: Hyko Date: Fri, 24 Apr 2026 17:47:08 -0400 Subject: [PATCH] docs: rewrite redaction guide with clearer structure and scope - split voice guidelines into two contexts: interface and documentation - replace generic editorial rules with format-specific sections (ui, labels, errors, doc) - remove site/email/proposal sections out of scope for this project - add concrete examples for interface messages, buttons, and error states - streamline typography and punctuation rules --- docs/dev/REDACTION.md | 230 +++++++++++++++++++----------------------- 1 file changed, 103 insertions(+), 127 deletions(-) diff --git a/docs/dev/REDACTION.md b/docs/dev/REDACTION.md index 526ce51..fc67309 100644 --- a/docs/dev/REDACTION.md +++ b/docs/dev/REDACTION.md @@ -1,163 +1,139 @@ -# RÉDACTION -Dernière modification : 2026-04-12 +# Rédaction -## La voix de l'entreprise - -On parle comme une personne, pas comme une organisation. Direct, sans fioritures. - -On dit **"on"** — jamais "nous sommes heureux de", jamais "notre équipe d'experts". Une seule exception : quand on cite quelqu'un nommément, on peut utiliser "je". - -La technique est là parce qu'elle est utile, pas pour impressionner. Si une explication technique ne sert pas le lecteur, elle ne sert pas le texte. +Ce guide s'applique à tout contenu textuel visible par l'utilisateur dans ce projet : l'interface admin, les messages d'état, les documentations dans `docs/` et les README. --- -## Ce qu'on évite absolument +## Deux contextes, deux voix -**Les superlatifs vides** -*de premier plan, leader, de pointe, best-in-class, incontournable* +**Interface (labels, messages, descriptions)** : la plateforme rapporte ce qui s'est passé. On utilise l'impersonnel et le passif descriptif. L'utilisateur est le sujet implicite. -**Les promesses floues** -*solutions sur mesure, accompagnement personnalisé, approche holistique* +**Documentation** : on s'adresse directement au développeur qui lit. Phrases courtes, verbes actifs, ton direct. + +--- + +## Ce qu'on évite partout + +**Superlatifs et formules vides** +*de premier plan, robuste, puissant, tout-en-un, intuitif, seamless* **Le corporate** -*nous nous engageons à, notre mission est de, dans une optique de, à cet effet* +*notre plateforme vous permet de, dans une optique de, à cet effet* -**La sur-promesse** -Si on ne peut pas le garantir, on ne l'écrit pas. Jamais. - -**Les métaphores usées** -*pont entre, clé en main, écosystème, synergies, à 360°* +**Chevilles inutiles** +*Ainsi, En effet, Il convient de noter que, N'hésitez pas à, Veuillez noter que* **Le tiret long (—)** -Reformuler la phrase plutôt que d'insérer une incise. +Reformuler la phrase à la place. -**Les chevilles inutiles** -*Ainsi, En effet, Il convient de noter que, N'hésitez pas à* - -**Le passif sans raison** -Préférer la forme active. "On a livré le projet" plutôt que "le projet a été livré". +**La sur-promesse** +Si on ne peut pas le garantir, on ne l'écrit pas. --- -## Formules qui marchent +## Interface -**Plutôt ça :** -> "On dit non quand c'est la bonne réponse." -> "On pense à comment les choses vont tenir dans six mois." -> "Ce n'est pas le bon projet pour nous. Voilà pourquoi." +### Voix de l'interface -**Pas ça :** -> "Notre approche centrée client garantit des résultats optimaux." -> "Nous mettons notre expertise au service de vos ambitions." -> "Une équipe passionnée à votre écoute." +La plateforme rapporte. Elle ne dit pas "on a fait" — elle dit ce qui s'est passé. -**La règle d'or :** si ça pourrait figurer dans la communication d'un concurrent sans changer un mot, c'est à réécrire. +> ✓ "Les modifications ont été enregistrées." +> ✓ "La page a été supprimée." +> ✗ "On a enregistré vos modifications." +> ✗ "Nous avons bien reçu votre demande." + +Pas de "vous" ni de "nous". L'état parle pour lui-même. + +### Labels et boutons + +Courts, un verbe d'action à l'infinitif, sans point. + +> ✓ "Enregistrer", "Supprimer", "Ajouter une page" +> ✗ "Cliquez ici pour enregistrer vos modifications" + +Pas de majuscule à chaque mot. + +> ✓ "Ajouter un élément" +> ✗ "Ajouter Un Élément" + +### Messages d'erreur + +Nommer ce qui ne va pas. Dire quoi faire si c'est utile. + +> ✓ "Ce champ est requis." +> ✓ "Ce slug est déjà utilisé. Choisir un autre." +> ✗ "Une erreur s'est produite. Veuillez réessayer." + +Pas de code d'erreur technique si l'utilisateur n'est pas développeur. + +### Messages de confirmation + +Une phrase. Ce qui s'est passé, au passé passif. Sans "avec succès". + +> ✓ "Page enregistrée." +> ✓ "Modifications enregistrées." +> ✓ "Élément supprimé." +> ✗ "Vos modifications ont été enregistrées avec succès !" + +### États vides + +Expliquer la situation, pas juste la constater. Ajouter l'action à faire si applicable. + +> ✓ "Aucune page pour l'instant. Créer la première." +> ✗ "Aucun résultat trouvé." + +### Textes d'aide et descriptions + +Une phrase. Répondre à "pourquoi" ou "comment", pas aux deux. + +> ✓ "Utilisé dans l'URL. Ne peut pas être modifié après publication." +> ✗ "Le slug est un identifiant unique utilisé pour générer l'URL de la page. Il doit être en minuscules et ne peut pas contenir d'espaces ou de caractères spéciaux." --- -## Structure des textes +## Documentation + +### Voix de la documentation + +On s'adresse directement au développeur. Verbes actifs, phrases courtes, sans intermédiaire. + +> ✓ "Le registre permet d'ajouter des widgets sans toucher au core. Importer `registerWidget` et passer un composant." +> ✗ "Le registre est un système centralisé qui permet la gestion modulaire des composants d'interface." + +### Structure + +- **Titre :** ce que le document permet de faire. +- **Première phrase :** pourquoi ce document existe, à qui il s'adresse. +- **Prérequis si nécessaire :** ce qu'il faut savoir ou avoir avant. +- **Corps :** une idée par section, titres descriptifs. +- **Notes :** à la fin, pas dans le milieu. ### Titres -Courts, affirmatifs, sans point. Une idée, pas une liste. Pas de question rhétorique. -> ✓ "Zéro raccourci. Zéro compromis." -> ✓ "On livre. On reste." -> ✗ "Une approche rigoureuse pour des résultats durables" -> ✗ "Pourquoi nous choisir ?" +Descriptifs, pas génériques. + +> ✓ "Ajouter un widget à l'admin" +> ✗ "Configuration" ### Corps de texte -Phrases courtes. Une idée par phrase. Maximum deux virgules par phrase — si on en compte plus, couper. -Paragraphes de trois à quatre phrases maximum. Une ligne blanche entre chaque paragraphe. +Phrases courtes. Une idée par phrase. Paragraphes de trois à quatre phrases maximum. -Pas de bullet points pour des concepts. Seulement pour des listes réelles (étapes, éléments techniques, options). +Commencer par un constat ou une situation concrète, pas par une définition. -### Appels à l'action -Concrets et à l'infinitif. Pas d'exclamation. - -> ✓ "Discuter de votre projet" -> ✓ "Voir comment on travaille" -> ✗ "Contactez-nous pour en savoir plus !" -> ✗ "Passez à l'action" +Pas de listes à puces pour des explications. Les listes servent pour les étapes, les options, les éléments techniques. --- -## Selon le format +## Révision avant de livrer -### Site web -Chaque page a une seule idée principale. Le visiteur doit comprendre l'essentiel en dix secondes. Les détails viennent après, pour ceux qui cherchent. - -Pas de jargon en page d'accueil. Le jargon technique appartient aux pages de service, là où le lecteur s'y attend. - -### Courriels -Objet : concret, pas accrocheur. Dire ce dont il s'agit, pas promettre quelque chose. - -> ✓ "Proposition — Refonte infrastructure" -> ✗ "Une opportunité à ne pas manquer" - -Corps du courriel : aller droit au but dès la première phrase. Pas de "j'espère que ce message vous trouve bien." Si on doit écrire plus de quatre paragraphes, se demander si c'est le bon format. - -### Applications et interfaces -Chaque message, étiquette ou instruction doit avoir un seul sens possible. Pas de formulation qui force l'utilisateur à interpréter. - -Le ton reste humain, même dans un contexte technique. "Une erreur s'est produite" est mieux que "Erreur 403 — accès non autorisé" si le lecteur n'est pas développeur. - -Les messages de confirmation, d'erreur et d'aide suivent les mêmes règles que le reste : courts, directs, actifs. - -### Articles et billets -Un angle précis, pas un survol. Mieux vaut un article sur un problème concis que dix paragraphes vagues. - -Commencer par un fait, un constat ou une situation — pas par une définition. - -> ✓ "La plupart des migrations ratent pour la même raison : on sous-estime ce qui dépend de ce qu'on déplace." -> ✗ "La migration de données est un processus complexe qui nécessite une planification rigoureuse." - -Terminer sur ce qu'on retient, pas sur une invitation à nous contacter. - -### Propositions et soumissions -Pas de section "qui sommes-nous" en ouverture. Le client le sait déjà ou s'en fout pour l'instant. - -Commencer par le problème du client, tel qu'on l'a compris. S'il se reconnaît dans les deux premiers paragraphes, le reste a de la valeur. - -La solution vient après le diagnostic. Jamais avant. - -### Documents internes -Mêmes règles de clarté que pour les textes externes. Un document interne mal écrit crée autant de confusion qu'une mauvaise communication client. - -Titres de section descriptifs, pas génériques. "Décision retenue et raison" est mieux que "Résultats". - -Si un document dépasse deux pages, se demander si l'information ne serait pas mieux transmise autrement. - -### Réseaux sociaux -Un seul message par publication. Si on a besoin d'un fil de publications pour expliquer, c'est probablement un article. - -Le ton reste celui de l'entreprise — pas plus décontracté sous prétexte que c'est un réseau social. - -Pas de hashtags décoratifs. Seulement ceux qui servent la découverte du contenu. +- [ ] La première phrase dit déjà l'essentiel. +- [ ] Chaque phrase dit quelque chose. Les phrases qui meublent sont supprimées. +- [ ] L'interface utilise l'impersonnel. La doc s'adresse directement au lecteur. +- [ ] Il n'y a pas de tiret long (—). +- [ ] Les fautes sont corrigées. +- [ ] L'utilisateur sait quoi faire ou quoi retenir après avoir lu. --- -## Parler de ce qu'on fait - -Ne jamais affirmer qu'on est "les meilleurs" ou "différents des autres". Le montrer, pas le dire. - -Quand on parle de ce qu'on fait, on parle de situations concrètes. Pas de généralités. - -> ✓ "On a refusé un mandat parce que le calendrier ne tenait pas." -> ✗ "On valorise l'honnêteté dans nos relations clients." - ---- - -## Révision d'un texte - -Avant de publier ou d'envoyer, se poser ces questions : - -1. **Est-ce qu'un concurrent pourrait signer ce texte ?** Si oui, réécrire. -2. **Est-ce qu'on promet quelque chose qu'on ne contrôle pas ?** Retirer ou nuancer. -3. **Est-ce que chaque phrase dit quelque chose ?** Supprimer celles qui ne font que meubler. -4. **Est-ce que le lecteur sait quoi faire ou quoi penser après ?** Si non, préciser. -5. **A-t-on utilisé le mot "solution" ?** Le remplacer. Presque toujours. - ---- - -*Ce guide évolue. Si une formule sonne faux ou si un cas n'est pas couvert, on l'ajuste.* \ No newline at end of file +*Ce guide évolue. Si une formule sonne faux ou si un cas n'est pas couvert, l'ajuster.*