zen/core

Files

T

hykocx e27fe939c5 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

2026-04-24 17:47:08 -04:00

4.2 KiB

Raw Blame History

Rédaction

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.

Deux contextes, deux voix

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.

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 notre plateforme vous permet de, dans une optique de, à cet effet

Chevilles inutiles Ainsi, En effet, Il convient de noter que, N'hésitez pas à, Veuillez noter que

Le tiret long (—) Reformuler la phrase à la place.

La sur-promesse Si on ne peut pas le garantir, on ne l'écrit pas.

Interface

Voix de l'interface

La plateforme rapporte. Elle ne dit pas "on a fait" — elle dit ce qui s'est passé.

✓ "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."

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

Descriptifs, pas génériques.

✓ "Ajouter un widget à l'admin" ✗ "Configuration"

Corps de texte

Phrases courtes. Une idée par phrase. Paragraphes de trois à quatre phrases maximum.

Commencer par un constat ou une situation concrète, pas par une définition.

Pas de listes à puces pour des explications. Les listes servent pour les étapes, les options, les éléments techniques.

Révision avant de livrer

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.

Ce guide évolue. Si une formule sonne faux ou si un cas n'est pas couvert, l'ajuster.

4.2 KiB Raw Blame History