Better Doc
Révisez les documents selon deux cadres complémentaires :
- Style Classique (Pinker) – Clarté, précision, nécessité
- Brièveté Intelligente (Axios) – Structure, lisibilité, impact
Objectif : Faire du texte une fenêtre transparente sur le sens. La brièveté, c’est la confiance ; la longueur, la peur.
Règle cruciale : Préserver le fond
Brièveté ≠ Suppression. Simplifiez l’expression, conservez le sens.
Lors de la révision de documents existants (en particulier les prompts) :
| À faire | À ne pas faire |
|---|---|
| Rendre les exigences verbeuses plus directes | Supprimer des exigences qui semblent longues |
| Condenser les explications bavardes | Retirer le contexte dont le lecteur a besoin |
| Remplacer les termes vagues par des termes spécifiques | Éliminer les contraintes ou les cas particuliers |
| Restructurer pour la clarté | Perdre des informations en restructurant |
Avant de couper quoi que ce soit, demandez-vous :
- Ce passage exprime-t-il une exigence, une contrainte ou un contexte ?
- Sa suppression changerait-elle le résultat ?
- Puis-je dire la même chose en moins de mots au lieu de supprimer ?
Pour les prompts en particulier :
- Exigences noyées dans des paragraphes → Extrayez-les sous forme de puces explicites
- Contraintes implicites → Rendez-les explicites, ne supposez pas qu’elles sont évidentes
- Contexte verbeux → Condensez-le, mais conservez-le s’il influence le comportement
- Exemples → Gardez-les s’ils clarifient des cas particuliers, supprimez-les s’ils sont redondants
Mauvaise approche : « Ce paragraphe est long, supprimez-le. » Bonne approche : « Ce paragraphe contient 3 exigences. Réécrivez-le sous forme de 3 puces. »
Principes fondamentaux
Style Classique (8 principes)
- Langage direct – Voix active, acteurs clairs
- Contenu nécessaire uniquement – Supprimez ce qui n’améliore pas la compréhension
- Pas de complexité artificielle – La structure sert la clarté, pas la décoration
- Spécifique plutôt qu’abstrait – Termes concrets et vérifiables
- Terminologie cohérente – Un seul nom par concept
- Intention claire – Objectif, contraintes, format de sortie (pour les prompts)
- Ordre centré sur le lecteur – La séquence suit le chemin de la compréhension
- Affirmations vérifiables – Faits et logique, pas d’impressions
Brièveté Intelligente (4 composants)
- Titre fort – 6 mots ou moins, captez l’attention
- Un seul message clé – Première phrase = la SEULE chose à retenir
- Pourquoi c’est important – Contexte sur la pertinence pour le lecteur
- Aller plus loin – Détails facultatifs, regroupés en puces
Pour des explications détaillées : references/principles.md
Flux de travail de révision
Étape 1 : Classer le document
| Type | Axes d’attention |
|---|---|
| Courriel/Mise à jour | Structure Brièveté Intelligente, lisibilité |
| Prompt/Instruction | Clarté de l’intention, contraintes, format |
| Document technique | Précision, terminologie, hiérarchie |
| Texte général | Style Classique, fluidité, nécessité |
Étape 2 : Vérifier la structure Brièveté Intelligente
Pour les courriels, mises à jour, annonces :
✓ Titre : ≤6 mots forts ?
✓ Première phrase : UN message clé ?
✓ « Pourquoi c’est important » : Pertinence pour le lecteur claire ?
✓ Détails : En puces, lisibles ?
✓ Gras : Termes clés mis en évidence ?
Étape 3 : Vérifier le Style Classique
| Principe | Signaux d’alerte |
|---|---|
| Langage direct | Voix passive, nominalisations, verbes enterrés |
| Contenu nécessaire | Bourrage, répétition, affirmations évidentes |
| Pas de complexité | Surformatage, puces imbriquées, titres inutiles |
| Spécifique | « Divers », « aspects », jargon non défini |
| Termes cohérents | Même chose, noms différents |
| Intention claire | Objectif manquant, contraintes vagues |
| Ordre lecteur | Sujets qui changent, conclusion avant le contexte |
| Vérifiable | « Il semble », affirmations non étayées |
Étape 4 : Vérifier les problèmes de mots
Règles de mots de la Brièveté Intelligente :
- Les mots courts gagnent : 1 syllabe > 2 > 3
- Coupez : Adverbes, mots faibles, mots de remplissage
- Verbes actifs toujours
| Coupez Ceci | Gardez/Remplacez Par |
|---|---|
| « Afin de » | « Pour » |
| « En raison du fait que » | « Parce que » |
| « À ce stade » | « Maintenant » |
| « Utiliser » | « Employer » |
| « Mettre en œuvre » | « Faire » / « Construire » |
| « Faciliter » | « Aider » / « Permettre » |
Étape 5 : Rapporter les résultats
## Résumé de la révision
**Type** : [courriel/prompt/technique/général]
**Global** : [évaluation en une ligne]
## Structure (Brièveté Intelligente)
- Titre : [✓/✗ + correctif]
- Première phrase : [✓/✗ + correctif]
- Pourquoi c’est important : [✓/✗ + correctif]
- Lisibilité : [✓/✗ + correctif]
## Style (Classique)
[Listez les violations avec emplacement, problème, correctif]
## Révision suggérée
[Version améliorée si demandée]
Référence rapide : Format Brièveté Intelligente
Pour les courriels et mises à jour, utilisez cette structure :
**[Titre en 6 mots]**
[UNE phrase : le message clé]
**Pourquoi c’est important** : [1-2 phrases sur la pertinence pour le lecteur]
**Prochaines étapes** / **Aller plus loin** / **Les détails** :
• [Puce 1]
• [Puce 2]
• [Puce 3]
**En résumé** : [Message de conclusion facultatif]
Vérifications spécifiques aux prompts
Structure cible :
Objectif : [Déclaration unique et claire]
Contraintes :
- [Limite 1]
- [Ce qu’il NE faut PAS faire]
- [Limites de longueur/format]
Format de sortie : [Structure exacte]
En améliorant des prompts existants :
| Problème d’origine | Correctif (PAS supprimer) |
|---|---|
| Exigence noyée dans le texte | Extraire → puce explicite |
| Contrainte vague (« soyez prudent ») | Rendre spécifique (« ne jamais dépasser X ») |
| Hypothèse implicite | Énoncer explicitement |
| Exemple redondant | Supprimer seulement si un autre exemple le couvre |
| Longue explication d’un cas particulier | Condenser, garder la règle |
Liste de vérification avant finalisation :
- Toutes les exigences originales sont-elles toujours présentes ?
- Les contraintes sont-elles plus explicites qu’avant ?
- Rien n’a été perdu dans la restructuration ?
- Plus court ET plus clair (pas seulement plus court) ?
Signaler : Objectif manquant, termes vagues (« bon », « approprié »), absence de format de sortie.
Correctifs courants
| Problème | Avant | Après |
|---|---|---|
| Passif | « Les données sont traitées » | « Le système traite les données » |
| Nominalisation | « Prendre une décision » | « Décider » |
| Bourrage | « Il est important de noter que » | [supprimer] |
| Mot long | « Utiliser » | « Employer » |
| Vague | « Divers facteurs » | « Coût, temps, périmètre » |
| Titre faible | « Mise à jour du projet » | « Le projet sort vendredi » |
| Entrée en matière enterrée | [paragraphe avant le point] | [point en premier] |
Compétences connexes
Fait partie d’une petite famille de compétences agent open source pour une communication fiable et claire :
- reduce-hallucination – Auditer les modèles LLM ; ancrer, citer, s’abstenir.
- better-doc – Style Classique + Brièveté Intelligente.
- numbers – Donner du sens aux nombres et les afficher proprement.