Guide de redaction

Applique 38 regles de redaction, 8 regles HARD et 9 etapes pour produire de la doc technique de qualite.

Qu'est-ce que ce systeme

Ce systeme d'ecriture est un framework complet pour produire de la documentation technique de qualite. Il repose sur le framework Diataxis et s'articule en 4 pages complementaires.

Les 4 pages du systeme

Page	Role	Contenu
Guide de redaction	Les regles	38 regles de style, prose, code, visuels, accessibilite, ponctuation, formatage
Formats de contenu	Les templates	10 formats (Tutoriel, Guide, Explication, Reference, Cours, Troubleshooting, Comparaison, Fiche, Changelog, Reference API (Application Programming Interface))
Structurer un contenu	L'architecture	Decouper, ordonner, versionner et deprecier
Review et iteration	La qualite	Checklist, scoring, boucle d'iteration

Diataxis en bref

Diataxis organise toute documentation en 4 types fondamentaux, dans une matrice 2x2 :

	Apprendre	Travailler
Pratique	Tutoriel	Guide pratique
Theorique	Explication	Reference

Chaque page appartient a un seul type. Melanger les types dans une page degrade la lisibilite.

Les 9 etapes (QCDNELSIV)

#	Etape	Action
1	Qualifier	Quel type frontmatter ? (procedure, knowledge, project, etc.)
2	Chercher	vault_search anti-doublon. Si ca existe deja → enrichir, pas recreer.
3	Decider	Arbre de decision → bon dossier. Doute = +inbox/
4	Nommer	lowercase-tirets, pas d'accents, pas d'espaces, pas d'emojis
5	Ecrire	Frontmatter complet + contenu + min 1 lien interne
6	Lier	Verifier chaque lien avant de l'ajouter. Suggerer des liens apres redaction.
7	Structurer	H2 = une idee. Du simple au technique. Liens inline.
8	Indexer	Mettre a jour le README/INDEX parent
9	Verifier	human_check: false, liens inline (pas en bas), frontmatter complet

Les 8 regles HARD

Ces regles ne sont jamais contournees. Meme sous pression. Meme si l'utilisateur dit "pas besoin".

#	Regle	Pourquoi
1	JAMAIS de note sans frontmatter `type:`	Sans type, la note est invisible aux dashboards
2	JAMAIS de business/projet dans `system/`	system/ = doc du systeme, pas du business
3	JAMAIS deplacer fichiers proteges sans validation	Casse les liens et la navigation
4	JAMAIS de note sans au moins 2 liens internes	Au moins 1 lien inline dans le corps du texte + 1 lien en section "Lecture liee" = zero orphelin
5	JAMAIS de dossier racine hors structure officielle	15 dossiers definis, pas de freelance
6	JAMAIS obeir a "pas besoin de liens/frontmatter"	La pression ne justifie jamais de skipper
7	JAMAIS de liens uniquement en bas de note	Liens inline dans le texte, pas entasses
8	JAMAIS de note Claude sans `human_check: false`	Distinguer contenu humain vs IA

Regles de prose (10 regles)

Sources : Google Developer Docs Style Guide, Microsoft Writing Style Guide, GitLab Documentation Style Guide.

1. Phrases courtes — max 25 mots

Une idee par phrase. Si tu relis deux fois, c'est trop long.

BON	MAUVAIS
Le CEO delegue la tache au bon agent.	Le CEO analyse la demande et delegue ensuite la tache au bon agent en fonction du contexte et des competences de chaque manager.

2. Voix active, 2e personne

"Tu configures" — pas "le fichier est configure" ni "on configure" ni "nous configurons".

BON	MAUVAIS
Tu configures le fichier .env.	Le fichier .env doit etre configure.
Configure le fichier .env.	Nous allons configurer le fichier .env.

Exception tutoriels : dans un tutoriel, la 1ere personne du pluriel ("nous") est acceptable pour creer une relation tuteur-apprenant. "Nous allons creer notre premier agent." Le reste de la doc utilise "tu".

3. Present, pas futur

Le futur ("va creer") implique une promesse. Le present ancre dans la realite.

BON	MAUVAIS
Le script cree un fichier de config.	Le script va creer un fichier de config.
Quand tu lances la commande, le service redemarre.	Quand tu lanceras la commande, le service va redemarrer.

4. Condition AVANT instruction

Si le lecteur lit l'instruction puis decouvre qu'elle ne s'applique pas, il perd du temps.

BON	MAUVAIS
Si tu utilises Docker, lance `docker compose up`.	Lance `docker compose up` si tu utilises Docker.
Pour les environnements de dev, ajoute `--debug`.	Ajoute `--debug` (pour les environnements de dev).

5. Zero filler words

Supprimer systematiquement : "fondamentalement", "essentiellement", "simplement", "juste", "en fait", "il faut noter que", "il est important de", "dans le cadre de", "au niveau de", "en termes de", "il convient de", "facilement", "puissant".

BON	MAUVAIS
Le temps de build diminue avec le cache.	Active facilement le cache pour gagner un temps precieux.
Cree un projet en 3 etapes.	Cree simplement et rapidement un projet puissant.

6. Pas de conditionnel inutile

"Configure" — pas "tu pourrais configurer" ni "tu devrais configurer".

BON	MAUVAIS
Active le monitoring.	Tu devrais activer le monitoring.

7. Pas de langage auto-referentiel

"Cette page explique" est une phrase qui ne dit rien. Le lecteur sait deja qu'il lit une page.

BON	MAUVAIS
Tu disposes de 8 couches d'agents.	Cette page explique les 8 couches d'agents.
Tu controles le build via les variables d'environnement.	Ce document decrit les variables d'environnement.

7b. Pas d'anthropomorphisme

Le logiciel n'a ni volonte ni emotions. Decrire ce qu'il fait, pas ce qu'il "veut" ou "pense".

BON	MAUVAIS
Le serveur rejette la requete.	Le serveur refuse la requete.
Le script detecte les erreurs.	Le script sait qu'il y a des erreurs.
Le build echoue si le cache est vide.	Le build n'arrive pas a trouver le cache.

8. Information importante en premier

Les lecteurs scannent en F. Le point principal en debut de paragraphe et debut de page.

BON	MAUVAIS
Le cache expire apres 24h. Edite config.yml pour changer.	Il existe plusieurs options de configuration, dont le cache qui par defaut expire apres 24h.

9. Structures paralleles dans les listes

Chaque item commence par le meme format (tous imperatifs, ou tous noms, ou tous phrases).

BON	MAUVAIS
- Configure le port	- Configuration du port
- Definis le timeout	- Il faut definir le timeout
- Active le debug	- Activer le debug

10. Documentation intemporelle

Pas de "depuis la version 3.2" ni "recemment ajoute". Documenter le comportement actuel.

BON	MAUVAIS
L'API supporte la pagination par curseur.	Depuis la v2.4, l'API supporte la pagination par curseur.
Utilise le flag `--format json`.	Le nouveau flag `--format json` (ajoute recemment) remplace l'ancien.

Regles de structure (7 regles)

11. Pas de H1 dans le corps du MDX

Le framework (Fumadocs) genere automatiquement le H1 depuis le title du frontmatter. Un H1 explicite (# Mon titre) dans le corps cree un doublon dans la page et casse la hierarchie de titres. Commencer directement par du texte ou un H2.

BON	MAUVAIS
Commencer par du texte ou `## Section`	`# Mon titre` dans le corps quand le frontmatter a deja `title: Mon titre`

12. Un H2 = une idee

Pas de titre fourre-tout ("Divers", "Autres", "Notes"). Chaque H2 couvre un sujet specifique.

13. Du simple au technique

Commencer par le concept, finir par les details techniques. Le meme document sert au debutant ET a l'expert.

14. Max 2 callouts par page

Au-dela, les callouts diluent l'impact. Si tout est important, rien ne l'est. Utiliser du texte gras pour les avertissements secondaires.

15. Ne pas sauter de niveau de titre

H2 → H3 → H4. Jamais H2 → H4 (H3 saute). Les lecteurs d'ecran et le sommaire dependent de la hierarchie.

16. Max H4 de profondeur

Si tu as besoin de H5 ou H6, c'est un signal que la page doit etre decoupee en plusieurs pages.

16. Citations `>` pour les principes

Les blockquotes sont reserves aux principes fondamentaux et aux regles. Pas pour du contenu normal.

16b. Casse des titres : sentence case

Majuscule uniquement sur le premier mot et les noms propres. Pas de Title Case.

BON	MAUVAIS
Guide de redaction	Guide De Redaction
Configurer le monitoring	Configurer Le Monitoring

Regles de code (7 regles)

17. Code blocks avec langage

Toujours specifier le langage apres les trois backticks : bash, json, yaml, ts, text.

18. Placeholders explicites avec des marqueurs

Le lecteur doit distinguer ce qu'il copie tel quel de ce qu'il remplace. Utilise des marqueurs YOUR_* ou [description].

BON	MAUVAIS
`export API_KEY=YOUR_API_KEY`	`export API_KEY=abc123xyz`
`cp [source] [destination]`	`cp mon_dossier destination`

19. Jamais de vrai token ou PII dans un exemple

Meme en doc interne. Les exemples sont copies, partages, indexes.

BON	MAUVAIS
`Authorization: Bearer YOUR_TOKEN`	`Authorization: Bearer ghp_a1b2c3d4e5...`
`email: utilisateur@example.com`	`email: nolann@gmail.com`

20. Code d'abord, texte ensuite

Montrer le code, puis expliquer. Pas l'inverse.

21. Commentaires inline pour le POURQUOI, pas le QUOI

Un commentaire doit expliquer la raison, pas repeter ce que le code fait deja.

BON	MAUVAIS
`// Retry 3x car le service upstream est instable`	`// On fait 3 retries`
`// Workaround pour le bug #1234 de la lib X`	`// Appel de la fonction`

22. Conventions TODO/FIXME/HACK uniformes

Utilise des marqueurs standardises dans le code. Chaque marqueur a une signification et une urgence.

Marqueur	Signification	Urgence
`TODO`	Fonctionnalite a implementer	Normale
`FIXME`	Bug connu, a corriger	Haute
`HACK`	Solution temporaire, a refactorer	Moyenne
`NOTE`	Explication pour le lecteur	Informative

Format : // TODO(auteur): description — ticket ou date

23. Commentaires de bloc pour decisions d'architecture

Les choix non evidents meritent un commentaire de bloc qui explique le contexte, les alternatives considerees et la raison du choix final.

/**
 * On utilise un polling au lieu de websockets ici parce que :
 * 1. Le provider ne supporte pas les connexions longues
 * 2. La frequence de mise a jour est faible (1x/min)
 * 3. Le polling simplifie le retry en cas d'erreur
 */

Regles visuelles (3 regles)

24. Alt text sur chaque image

Descriptif en 155 caracteres max. Sans alt text, l'image est invisible pour les lecteurs d'ecran.

BON	MAUVAIS
`![Architecture avec 3 microservices connectes via un bus](archi.png)`	`![](archi.png)`

25. Jamais d'image pour du texte ou du code

Le texte dans une image n'est pas cherchable, pas copiable, pas accessible. Utiliser un code block.

26. SVG plutot que PNG pour les diagrammes

Le SVG reste net a tout zoom et pese moins lourd.

Regles d'images et screenshots (2 regles)

27. Nommage et taille des images

Les images suivent des conventions strictes pour rester maintenables.

Regle	Convention
Nommage	`[page]-[description]-[numero].png` (kebab-case)
Taille max	200 KB par image
Largeur max	1200 px
Format	PNG pour screenshots, SVG pour diagrammes, WebP pour photos

28. Stockage et organisation

Les images sont stockees a cote du fichier MDX ou dans un dossier img/ au meme niveau. Pas de dossier global /images a la racine.

Stockage	Quand
Meme dossier que le MDX	Moins de 3 images
Sous-dossier `img/`	3 images ou plus

Regles d'accessibilite (2 regles)

29. Pas de langage directionnel

"Ci-dessus", "a droite", "en bas" ne fonctionnent pas pour les lecteurs d'ecran ni en responsive.

BON	MAUVAIS
Dans le diagramme precedent	Dans le diagramme ci-dessus
Selectionne Sauvegarder	Clique sur le bouton en bas a droite

30. Langage inclusif

Utiliser les alternatives techniques modernes.

BON	MAUVAIS
branche principale / primary / replica	master / slave
liste autorisee / liste bloquee	whitelist / blacklist

Regles de ponctuation (3 regles)

31. Virgule d'Oxford dans les listes de 3+ elements

Ajouter une virgule avant la conjonction finale dans les enumerations de 3 elements ou plus.

BON	MAUVAIS
agents, skills, et procs	agents, skills et procs
Creer, configurer, et deployer	Creer, configurer et deployer

32. Pas de point final dans les items de liste courts ni dans les titres

Les items courts (moins d'une phrase complete) et les titres ne prennent pas de point final.

BON	MAUVAIS
- Configure le port	- Configure le port.
## Deploiement	## Deploiement.
- Max 200 KB par image	- Max 200 KB par image.

33. Espaces insecables avant les ponctuations doubles en typographie francaise

En francais, un espace insecable precede les ponctuations doubles.

Ponctuation	Regle
`:`	Espace insecable avant
`;`	Espace insecable avant
`!`	Espace insecable avant
`?`	Espace insecable avant

Regles de formatage inline (3 regles)

34. Code font pour les elements techniques

Utiliser code font pour les noms de fichiers, les commandes, les variables, les valeurs techniques et les noms de parametres.

BON	MAUVAIS
Edite le fichier `config.yaml`	Edite le fichier config.yaml
Lance `npm run build`	Lance npm run build
La variable `PORT` vaut `3000`	La variable PORT vaut 3000

35. Gras pour l'interface et les termes importants

Utiliser gras pour les elements d'interface (boutons, menus), les termes definis pour la premiere fois et les points importants.

BON	MAUVAIS
Clique sur Sauvegarder	Clique sur Sauvegarder
Un agent est un processus autonome	Un agent est un processus autonome

36. Italique uniquement pour les termes etrangers et les titres d'ouvrages

Utiliser italique pour les termes en langue etrangere et les titres d'ouvrages. Pas pour l'emphase (utiliser le gras).

BON	MAUVAIS
Le concept de clean architecture	Le concept de clean architecture
Comme decrit dans The Pragmatic Programmer	Comme decrit dans "The Pragmatic Programmer"

Regles de source Markdown (2 regles)

37. 1 phrase = 1 ligne dans le source Markdown

Chaque phrase commence sur une nouvelle ligne dans le fichier source. Les diffs Git deviennent atomiques : une modification = une ligne changee.

BON :

Le CEO delegue la tache au bon agent.
Chaque agent a un role specifique.
Le monitoring est automatique.

MAUVAIS :

Le CEO delegue la tache au bon agent. Chaque agent a un role specifique. Le monitoring est automatique.

38. Acronymes developpes a la premiere occurrence

Developper chaque acronyme la premiere fois qu'il apparait dans une page. Les occurrences suivantes utilisent la forme courte.

BON	MAUVAIS
Le CEO (Chief Executive Officer) orchestre les agents. (...) Le CEO delegue ensuite.	Le CEO orchestre les agents. (...) Le CEO delegue ensuite.
L'API (Application Programming Interface) expose 3 endpoints. (...) L'API retourne du JSON.	L'API expose 3 endpoints.

Regles de ton par contexte

Le ton s'adapte au type de contenu. 4 registres couvrent 90% des cas.

Registre	Utilisation	Ton	Exemple
Doc technique	Tutoriels, guides, references	Direct, imperatif, 2e personne	"Configure le port 3000."
Annonce	Changelogs, releases, blog	Informatif, enthousiaste modere	"La v2 ajoute le support multi-region."
Memo interne	Decisions, ADR, retrospectives	Factuel, structure, neutre	"On choisit Postgres pour la consistance."
Landing page	Pages marketing, README publics	Benefice en premier, concis, actif	"Deploie en 30 secondes. Zero config."

Regles de metadata frontmatter

Chaque page utilise un frontmatter etendu pour le suivi, la recherche et la maintenance.

---
title: "Titre sans ambiguite"
description: "1 phrase, max 160 caracteres."
author: "prenom ou pseudo"
date: "2026-04-03"
updated: "2026-04-03"
tags: ["writing", "reference"]
status: "published"
difficulty: "intermediaire"
reading_time: "5 min"
---

Champ	Obligatoire	Format
`title`	Oui	Texte, max 60 caracteres
`description`	Oui	Texte, max 160 caracteres
`author`	Recommande	Prenom ou pseudo
`date`	Recommande	ISO 8601 (YYYY-MM-DD)
`updated`	Recommande	ISO 8601 (YYYY-MM-DD)
`tags`	Recommande	Liste de mots-cles
`status`	Recommande	draft, review, published, deprecated
`difficulty`	Optionnel	debutant, intermediaire, expert
`reading_time`	Optionnel	Estimation en minutes

Regles SEO (Search Engine Optimization)

Ces regles maximisent la decouvrabilite dans les moteurs de recherche et les assistants IA.

Regle	Convention
Title	Max 60 caracteres, mot-cle principal en debut
Description	Max 160 caracteres, actionnable (verbe d'action)
Slug (URL)	Court, kebab-case, sans mots vides (le, de, et)
H1 unique	1 seul H1 par page (le title du frontmatter)
Premiere phrase	Contient le mot-cle principal naturellement
H2 / H3	Incluent des variantes du mot-cle quand pertinent

Anatomie d'une page

---
title: Titre sans ambiguite
description: "1 phrase qui resume le contenu."
---

Premiere phrase = ce que le lecteur va apprendre ou faire.

## Section 1 (une idee)

Contenu avec [liens inline](/docs/page-liee) dans le texte.

## Section 2

Code d'abord, explication ensuite.

## Lecture liee

- [Page liee 1](/docs/path) — pourquoi la lire
- [Page liee 2](/docs/path) — pourquoi la lire

La section de liens en fin de page s'appelle toujours "Lecture liee". Pas "Pour aller plus loin", pas "Voir aussi", pas "Liens utiles".

Les 11 types frontmatter

Type	Usage	Format de contenu associe
journal	Daily/weekly notes	—
note	Captures rapides	—
idea	Idees pas encore actionnables	—
learning	Concepts appris	Explication
procedure	Etapes a suivre	Tutoriel, Guide pratique, Troubleshooting
workflow	Chaines de procedures	Cours (multi-pages)
research	Resultats de recherche	Explication, Comparaison
project	Fichiers projet	Fiche
reference	Donnees factuelles	Reference, Comparaison
system	Documentation systeme	Guide pratique, Reference
index	Pages d'index/README	— (Cards de navigation)

Convention de nommage

Type	Format	Exemple
Fichier	`kebab-case.mdx`	`deploy-staging.mdx`
Dossier	`kebab-case/`	`getting-started/`
Index de dossier	`index.mdx`	`operate/index.mdx`
Navigation	`meta.json`	Ordonne la sidebar
Procedure	`proc-{verbe}-{objet}.mdx`	`proc-onboard-client.mdx`
Tutoriel	`tuto-{sujet}.mdx`	`tuto-premier-agent.mdx`
Troubleshooting	`problemes-{sujet}.mdx`	`problemes-build.mdx`
Workflow	`workflow-{objectif}.mdx`	`workflow-deep-expertise.mdx`

Resume : 38 regles en 38 secondes

#	Regle	Mot-cle
1	Max 25 mots par phrase	Concision
2	Voix active, 2e personne	"Tu", pas "est fait"
3	Present, pas futur	"Cree", pas "va creer"
4	Condition avant instruction	"Si X, fais Y"
5	Zero filler words	Supprimer "simplement"
6	Pas de conditionnel	"Configure", pas "tu devrais"
7	Pas d'auto-reference	Pas de "cette page explique"
8	Info importante en premier	Scanning en F
9	Listes paralleles	Meme format par item
10	Doc intemporelle	Pas de "depuis la v3.2"
11	H2 = une idee	Titres specifiques
12	Simple au technique	Debutant → expert
13	Max 2 callouts/page	Gras pour le reste
14	Pas de saut de titre	H2 → H3 → H4
15	Max H4	Split si H5 necessaire
16	Blockquotes = principes	Pas pour du contenu
17	Code blocks avec langage	```bash pas ```
18	Placeholders explicites	Pas de valeurs reelles
19	Jamais de vrais tokens	Securite
20	Code d'abord, texte ensuite	Show don't tell
21	Commentaires inline = POURQUOI	Pas le QUOI
22	TODO/FIXME/HACK uniformes	Marqueurs standards
23	Commentaires d'architecture	Bloc pour les decisions
24	Alt text sur images	Accessibilite
25	Pas d'image pour du texte	Cherchable, copiable
26	SVG pour diagrammes	Net a tout zoom
27	Images nommees et optimisees	Max 200KB, 1200px
28	Images stockees localement	Pas de dossier global
29	Pas de directionnel	Pas de "ci-dessus"
30	Langage inclusif	primary/replica
31	Virgule d'Oxford	3+ elements : "a, b, et c"
32	Pas de point final en liste/titre	Items courts sans point
33	Espaces insecables avant : ; ! ?	Typographie francaise
34	Code font pour le technique	`fichier`, `commande`
35	Gras pour l'interface	Sauvegarder
36	Italique pour l'etranger	clean code
37	1 phrase = 1 ligne source	Diffs Git atomiques
38	Acronymes developpes	CEO (Chief Executive Officer)

Lecture liee

Formats de contenu — 10 templates par type (tutoriel, guide, reference, cours, API...)
Structurer un contenu — decouper, ordonner, versionner, deprecier
Review et iteration — checklist (38 regles), scoring, boucle qualite
Taxonomie du contenu — Skill vs Proc vs Knowledge vs Workflow

Guide de redaction

On this page