hykocx
74ce6192f1
- update README.md to simplify @zen/core description - rewrite DEV.md standards section with clearer principles and remove publication section - extract publication process to new PUBLICATION.md document - rewrite REDACTION.md with simplified structure and two-context approach - bump package version in package.json
140 lines
4.2 KiB
Markdown
140 lines
4.2 KiB
Markdown
# 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.*
|