Structurer un contenu

Bien ecrire ne suffit pas. Un bon contenu mal structure reste illisible. Voici comment organiser — avant, pendant et apres l'ecriture.

Avant d'ecrire : les 4 questions

Reponds a ces questions AVANT d'ouvrir l'editeur.

Adapter au public

Si tu ne connais pas ton public, ecris pour un intermediaire. C'est le compromis le plus sur.

Decouper : quand et comment split

Signaux qu'il faut split

Comment split

AVANT (1 page de 3000 mots) :

  # Deploiement
  ## Concepts
  ## Configuration
  ## Deployer en staging
  ## Deployer en production
  ## Troubleshooting
  ## Rollback

APRES (3 pages) :

  deploiement/
  ├── index.mdx      → Vue d'ensemble + liens (Explication)
  ├── deployer.mdx    → Staging + prod (Guide pratique)
  └── problemes.mdx   → Troubleshooting + rollback (Troubleshooting)

Chaque page apres split doit fonctionner seule. Pas de "voir page precedente pour le contexte".

Ordonner : dans quel ordre presenter

Ordre par defaut (fonctionne dans 80% des cas)

1. QUOI     → Ce que c'est (1-2 phrases)
2. POURQUOI → Quel probleme ca resout
3. COMMENT  → Les etapes ou le mecanisme
4. EXEMPLES → Concret, copiable
5. LIMITES  → Ce que ca ne fait pas
6. LIENS    → Lecture liee

Ordres alternatifs par format

Choisir le bon format visuel

Table vs Liste vs Prose vs Code

Regle du "scan test"

Apres avoir ecrit une section, demande-toi : un lecteur presse qui scanne en 5 secondes, trouve-t-il l'info qu'il cherche ?

• Si l'info est enterree dans un paragraphe → extraire en table ou liste
• Si une table a 2 colonnes et 2 lignes → remplacer par une phrase
• Si un code block n'a qu'une ligne → le mettre inline avec backticks

Longueur par type de contenu

Si tu depasses le max, c'est un signal de split, pas un probleme de concision.

Lier les pages entre elles

Regle du triangle

Chaque page doit etre accessible depuis au moins 3 chemins :

1. Sidebar (meta.json)
2. Lien inline depuis une autre page
3. Section "Lecture liee" d'une page parente

Types de liens

Un lien inline dit "approfondir ici". Un lien en fin de page dit "lire ensuite".

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

Nommer les fichiers et dossiers

Les conventions de nommage sont centralisees dans le Guide de redaction.

Depreciation et archivage

Chaque page a un cycle de vie. Gere-le explicitement.

Cycle de vie d'une page

draft → review → published → deprecated → archived

Qui decide de deprecier

Le mainteneur de la section ou l'auteur de la page. En cas de doute, le mainteneur a le dernier mot.

Frontmatter d'une page deprecated

---
title: "Titre de la page"
description: "..."
status: "deprecated"
deprecated_since: "2026-04-01"
deprecated_redirect: "/docs/reference/nouvelle-page"
---

Le champ deprecated_redirect est lu par le framework pour generer la redirection automatiquement. Pas besoin de configurer un redirect manuel.

Callout de depreciation

Ajoute un composant Callout en haut de chaque page deprecated :

<Callout type="warn">
  Page deprecated. Ce contenu est obsolete.
  Utilise [la nouvelle page](/docs/reference/nouvelle-page) a la place.
</Callout>

Liens entrants

Quand tu deprecies une page, mets a jour les liens inline qui pointent vers elle dans les autres pages. Le redirect via deprecated_redirect est un filet de securite, pas une excuse pour laisser des liens obsoletes.

Regle des 90 jours

90 jours apres la depreciation, la page est archivee sauf decision contraire du mainteneur. Pas de mesure de trafic complexe : le delai de 90 jours suffit.

Checklist pre-archivage

• 90 jours ecoules depuis la depreciation
• Tous les liens internes vers cette page mis a jour
• Le deprecated_redirect pointe vers une page active
• Le mainteneur a valide l'archivage
• Le meta.json parent sera mis a jour
• Le changelog sera mis a jour

Archivage

Quand une page passe en archived :

1. Deplacer le fichier dans archive/[dossier-original]/[fichier].mdx
2. Retirer la page de meta.json (au moment de l'archivage, pas de la depreciation)
3. Le redirect reste actif via le frontmatter deprecated_redirect

Versioning de la documentation

Quand la doc couvre plusieurs versions majeures d'un produit, utilise une strategie par dossiers.

Strategie dossiers

docs/
├── v1/
│   ├── getting-started.mdx
│   └── api-reference.mdx
├── v2/
│   ├── getting-started.mdx
│   └── api-reference.mdx
└── latest/ → symlink vers v2/

Regles de versioning

Internationalisation (i18n)

Quand le contenu doit exister en plusieurs langues, suis ce workflow.

Convention de fichiers

docs/
├── fr/
│   ├── getting-started.mdx
│   └── api-reference.mdx
├── en/
│   ├── getting-started.mdx
│   └── api-reference.mdx

Workflow de traduction

Glossaire partage

Maintiens un fichier glossary.yaml a la racine. Il contient les traductions officielles des termes techniques pour garantir la coherence.

# glossary.yaml
terms:
  agent:
    fr: "agent"
    en: "agent"
  workflow:
    fr: "workflow"
    en: "workflow"
  pipeline:
    fr: "pipeline"
    en: "pipeline"
  deploy:
    fr: "deployer"
    en: "deploy"
  build:
    fr: "build"
    en: "build"
  cache:
    fr: "cache"
    en: "cache"
  rollback:
    fr: "rollback"
    en: "rollback"
  token:
    fr: "token"
    en: "token"
  framework:
    fr: "framework"
    en: "framework"
  skill:
    fr: "skill"
    en: "skill"
  proc:
    fr: "proc"
    en: "proc"
  template:
    fr: "template"
    en: "template"
  callout:
    fr: "callout"
    en: "callout"
  frontmatter:
    fr: "frontmatter"
    en: "frontmatter"
  slug:
    fr: "slug"
    en: "slug"
  troubleshooting:
    fr: "depannage"
    en: "troubleshooting"

Frontmatter i18n

---
title: "Guide de demarrage"
i18n_status: "source"       # source | translated | outdated
i18n_source: "fr/getting-started.mdx"
---

Contribution externe

Quand des contributeurs externes participent a la documentation, suis ce workflow.

Workflow fork/PR

Template de PR

## Type de changement
- [ ] Nouvelle page
- [ ] Modification de page existante
- [ ] Correction (typo, lien mort, erreur factuelle)

## Pages impactees
- [liste des fichiers modifies]

## Checklist
- [ ] Frontmatter complet (title + description)
- [ ] Type Diataxis identifie
- [ ] Min 2 liens internes
- [ ] Section "Lecture liee" presente
- [ ] Build local passe sans erreur

Regles pour les contributeurs

Automatiser les regles

Deux outils recommandes pour appliquer les regles automatiquement :

Configure-les dans le CI (Continuous Integration) pour bloquer les PRs qui violent les regles. Les fichiers de config vivent a la racine du repo (.vale.ini, .markdownlint.json).

Checklist structurelle

Avant de publier, verifie :

• Le type de contenu est identifie (tuto, guide, explication, reference, cours, troubleshooting, comparaison, fiche, changelog)
• Le public est identifie (debutant, intermediaire, expert, decision-maker)
• La page fait moins de 2000 mots (sinon split)
• L'ordre suit le pattern du format (QUOI → POURQUOI → COMMENT → EXEMPLES)
• Les donnees structurees sont en tables, pas en prose
• Chaque section fait moins de 3 ecrans de scroll
• Au moins 2 liens internes (inline + lecture liee)
• Le fichier a un index.mdx dans son dossier parent
• Le fichier est liste dans le meta.json parent

Lecture liee

• Regles de redaction — les 38 regles de style
• Formats de contenu — 10 templates par type
• Review et iteration — checklist, scoring, boucle qualite