Conventions de documentation¶
Ce guide est la reference pour ecrire, structurer et maintenir la documentation technique des projets de l'organisation. Il couvre la philosophie (Diataxis), l'organisation des fichiers, la structure des pages, les fonctionnalites MkDocs Material, le style redactionnel et les pieges courants. Tout contributeur a la documentation doit le lire avant d'ecrire sa premiere page.
Portee¶
Ce standard s'applique a tous les contributeurs qui redigent ou modifient de la documentation sur les projets de l'organisation. Les conventions couvrent la structure, le style, l'outillage MkDocs Material et les bonnes pratiques de redaction.
Philosophie — le framework Diataxis¶
Les 4 types de documentation¶
Toute documentation technique se decompose en quatre categories distinctes. Chaque page appartient a exactement une categorie. Melanger les categories dans une meme page produit un document confus qui ne satisfait personne.
| Type | Question du lecteur | Ton | Exemples |
|---|---|---|---|
| Tutoriel | "Comment je demarre ?" | Pedagogique, pas a pas | Demarrage/installation.md |
| Guide pratique | "Comment je fais X ?" | Direct, oriente resultat | Exploitation/service.md |
| Reference | "Quel est le detail exact de Y ?" | Exhaustif, factuel | Reference/configuration.md |
| Explication | "Pourquoi ca marche comme ca ?" | Narratif, conceptuel | Learning/rate-limiting.md |
Ne pas melanger
Un guide d'installation (tutoriel) ne doit pas expliquer en profondeur un concept interne (explication). Il doit renvoyer vers la page Learning correspondante.
Principes de redaction¶
- Un seul sujet par page. Si le titre contient "et", c'est probablement deux pages.
- Le lecteur ne lit pas tout. Il scanne. Titres, tableaux, admonitions et blocs de code sont lus en premier.
- Montrer, puis expliquer. Un bloc de code commente vaut mieux qu'un paragraphe. Un diagramme Mermaid vaut mieux que trois paragraphes de description.
- Lier plutot que dupliquer. La duplication cree de la dette documentaire.
- Ecrire pour le cas d'usage le plus courant. Les cas particuliers vont dans des details collapsibles (
???).
Organisation des fichiers¶
Arborescence¶
La documentation suit une hierarchie a deux niveaux maximum.
Docs/
+-- index.md # Page d'accueil (grille de navigation)
+-- Demarrage/ # Tutoriels de premier lancement
+-- Exploitation/ # Guides pratiques d'exploitation
| +-- Depannage/ # Sous-section depannage (si volumineuse)
+-- Architecture/ # Explications de l'architecture interne
+-- Learning/ # Explications des concepts fondamentaux
+-- Reference/ # Documentation de reference exhaustive
+-- Includes/ # Fragments partages (glossaire)
Chaque projet peut adapter cette structure a ses besoins tant que la hierarchie reste a 2 niveaux maximum et que chaque dossier correspond a un type de documentation clair.
Nommage des fichiers¶
| Regle | Exemple correct | Exemple incorrect |
|---|---|---|
| Minuscules uniquement | installation.md |
Installation.md |
| Tirets pour les espaces | mise-a-jour.md |
mise_a_jour.md |
| Pas d'accents dans les noms | demarrage.md |
demarrage.md |
| Nom descriptif, court | service.md |
gestion-du-service-systemd.md |
| Pas de numerotation | daemon-core.md |
01-daemon-core.md |
L'ordre des pages est defini dans mkdocs.yml, pas par les noms de fichiers.
Regle des 300 lignes¶
Une page ne devrait jamais depasser 300-400 lignes de Markdown. Au-dela, le lecteur se perd et la page devient difficile a maintenir.
Exception : le dossier Reference/ est exempte si le contenu est tabulaire ou sous
forme de dictionnaire (liste exhaustive de parametres de configuration, par exemple).
Quand creer un nouveau fichier¶
| Creer un fichier | Ajouter a un fichier existant |
|---|---|
| Le sujet ne rentre dans aucune page existante | Le sujet est un complement naturel |
| Le contenu depasse 150 lignes s'il est ajoute | L'ajout ne depasse pas 50 lignes |
| Le sujet a un public different | Le public cible est le meme |
| Le sujet merite une entree dans la navigation | Pas besoin d'etre trouve independamment |
Navigation (mkdocs.yml)¶
Structure de la nav¶
La navigation doit etre :
- Plate : 2 niveaux maximum (section + page), 3 dans les cas exceptionnels
- Previsible : le lecteur devine ou se trouve l'information avant de cliquer
- Complete : toute page
.mddansdocs/doit apparaitre dans la nav
nav:
- Accueil: index.md
- Section thematique:
- Sous-titre clair: section/page-a.md
- Autre sous-titre: section/page-b.md
Bonnes pratiques¶
| Pratique | Detail |
|---|---|
| Titres nav courts (2-4 mots) | Installation, pas Guide complet d'installation du projet |
| Grouper par parcours utilisateur | Par usage, pas par type de document |
| Limiter la profondeur | 2 niveaux max, jamais 4 niveaux imbriques |
Structure d'une page¶
Anatomie obligatoire¶
# Titre de la page
> **Phrase d'accroche en gras.** Suite du resume en 1-2 phrases.
---
## Premiere section H2
Contenu...
---
## Deuxieme section H2
Contenu...
| Element | Obligatoire | Role |
|---|---|---|
H1 (#) |
Oui | Un seul par page. Titre complet du sujet. |
Blockquote d'intro (>) |
Oui | Resume scannable. Le lecteur decide en 5 secondes s'il est sur la bonne page. |
Separateur (---) |
Oui | Entre chaque section H2. Separation visuelle claire. |
Sections H2 (##) |
Oui | Divisions principales. Apparaissent dans la table des matieres. |
Sections H3 (###) |
Selon besoin | Sous-divisions. Aussi dans la table des matieres. |
Les H4 (####) sont autorises avec parcimonie pour micro-structurer une section complexe,
mais ils ne sont pas dans la table des matieres.
Templates par type de page¶
Page Learning (explication)¶
# Concept
> Resume accessible en 1-2 phrases.
---
## Le concept (analogie, explication technique)
---
## Exemples concrets
---
## Dans le projet (pourquoi, implementation, configuration)
---
## Pour aller plus loin
Page Exploitation (guide pratique)¶
# Operation
> Resume.
!!! info "Prerequis"
Liste des prerequis.
---
## Vue d'ensemble (optionnel)
---
## Procedure etape par etape
---
## Depannage (si pertinent)
Page Reference¶
# Sujet de reference
> Audience et couverture.
---
## Vue d'ensemble (tableau recapitulatif)
---
## Section A (par categorie logique)
---
## Section B
Page Depannage¶
Chaque probleme suit le pattern symptome-cause-solution :
### Symptome observable
!!! failure "Message d'erreur ou comportement"
Description exacte.
**Causes possibles :**
1. Cause 1
2. Cause 2
**Solutions :**
[Commandes et verifications pour chaque cause]
Fonctionnalites MkDocs Material¶
Admonitions (!!!)¶
| Type | Syntaxe | Quand l'utiliser |
|---|---|---|
tip |
!!! tip "Titre" |
Bonne pratique, astuce |
info |
!!! info "Titre" |
Contexte supplementaire |
note |
!!! note "Titre" |
Detail technique non essentiel |
warning |
!!! warning "Titre" |
Piege courant |
danger |
!!! danger "Titre" |
Erreur fatale, perte de donnees |
failure |
!!! failure "Titre" |
Message d'erreur (pages depannage) |
Regles d'usage :
- Maximum 3-4 admonitions par section H2
- Le titre est obligatoire (pas de
!!! warningsans titre) - Le contenu tient en 1-4 lignes (sinon, utiliser
???) - Ne pas enchainer deux admonitions sans texte entre elles
Details collapsibles (???)¶
Cachent du contenu secondaire derriere un clic. Essentiels pour garder les pages scannables.
???: ferme par defaut (sorties longues, alternatives rares, exemples supplementaires)???+: ouvert par defaut (checklists importantes mais volumineuses)
Regle : si un bloc depasse 10 lignes et n'est pas le sujet principal, l'envelopper dans ???.
Tabs (===)¶
Presentent des alternatives paralleles (jamais des etapes sequentielles).
| Situation | Utiliser tabs ? |
|---|---|
| Plusieurs OS / gestionnaires de paquets | Oui |
| Plusieurs outils pour la meme tache | Oui |
| Etapes sequentielles d'une procedure | Non |
| Niveaux de detail differents | Non (???) |
Regles : 2-5 tabs max, labels courts (1-3 mots), contenu de longueur similaire, indentation de 4 espaces.
Diagrammes Mermaid¶
Toujours preferables a l'ASCII art (qui casse sur mobile) et aux images (non editables).
| Type | Usage |
|---|---|
flowchart |
Flux de donnees, pipelines, processus decisionnels |
stateDiagram-v2 |
Machines a etats, lifecycle |
sequenceDiagram |
Interactions temporelles entre composants |
Regles : <br> pour les retours a la ligne (jamais \n), guillemets doubles autour
des labels avec caracteres speciaux, maximum 10-12 noeuds par diagramme.
Blocs de code¶
| Regle | Exemple correct | Exemple incorrect |
|---|---|---|
| Toujours specifier le langage | ```bash |
``` |
| Toujours ajouter un titre | ```bash title="Verifier" |
```bash (sans titre) |
Commandes executables avec sudo |
sudo systemctl status mon-service |
$ sudo systemctl... |
| Pas de sortie melangee | Commande et sortie dans des blocs separes | Tout dans le meme bloc |
hl_lines pour surligner |
```bash hl_lines="3" |
Pas de surlignage sur ligne critique |
Le titre du bloc de code remplace le paragraphe introductif ("Pour verifier, executez :").
Liens et references croisees¶
Liens internes¶
Utiliser des chemins relatifs pour tous les liens entre pages :
[rate limiting](../Learning/rate-limiting.md)
[configuration](configuration.md)
[les 3 etats](../Learning/circuit-breaker.md#les-3-etats)
Jamais de liens absolus (https://...) vers une autre page de la meme documentation.
Premiere occurrence¶
Chaque premiere occurrence d'un terme technique complexe dans une page doit etre liee vers sa page d'explication. Les occurrences suivantes ne sont pas liees.
Glossaire¶
Le fichier Docs/Includes/glossary.md fournit des tooltips automatiques via
l'extension pymdownx.snippets. Les abreviations definies sont automatiquement
soulignees en pointille sur toutes les pages avec une infobulle au survol.
Regles du glossaire :
- Definitions courtes (1 phrase, ~15 mots max)
- Le terme doit correspondre exactement au texte dans les pages (sensible a la casse)
- Pas de Markdown dans la definition
- Ajouter un terme s'il apparait sur 3+ pages differentes
- Les acronymes fondamentaux du domaine vont systematiquement dans le glossaire
Style redactionnel¶
Langue¶
- Francais avec accents partout (titres, texte, tableaux, admonitions)
- Exception : le contenu des blocs de code (commandes, commentaires en anglais)
- Les noms de fichiers n'ont pas d'accents (
demarrage.md)
Ton¶
| Contexte | Ton |
|---|---|
| Tutoriels | Accompagnant, etape par etape |
| Guides pratiques | Direct, imperatif |
| References | Factuel, neutre |
| Learning | Pedagogique, analogies |
Voix et personne¶
- Voix active preferee a la voix passive
- Imperatif pour les instructions : "Executez", "Verifiez"
- "Vous" pour s'adresser au lecteur dans les tutoriels et guides
- "On" pour les explications generales
- Pas de "nous" sauf dans les sections "Dans le projet"
Mise en forme du texte¶
| Mise en forme | Usage |
|---|---|
| Gras | Terme introduit pour la premiere fois, mot cle |
| Italique | Titres d'ouvrages, mots etrangers non techniques |
Code inline |
Commandes, noms de fichiers, valeurs de config, types |
| ~~Barre~~ | Ne pas utiliser |
Conventions specifiques¶
- Noms de composants : toujours en
code inlineavec la casse exacte du code - Chemins de fichiers : toujours en
code inline - Commandes : toujours dans un bloc de code avec titre, jamais inline
- Acronymes : definis a la premiere occurrence, puis utilises seuls
Pieges courants¶
| Erreur | Pourquoi c'est un probleme | Solution |
|---|---|---|
| Dupliquer du contenu entre pages | Maintenance impossible | Lien vers la source unique |
| Page de plus de 400 lignes | Illisible | Segmenter en plusieurs pages |
| 5+ admonitions dans une section | Le lecteur ne sait plus quoi lire | 2-3 max par section |
| Tabs pour des etapes sequentielles | Le lecteur ne lit qu'un tab | H3 numerotes |
| Bloc de code sans langage ni titre | Pas de coloration, pas scannable | Toujours specifier les deux |
Mermaid avec \n au lieu de <br> |
\n s'affiche litteralement |
Utiliser <br> |
| Liens absolus entre pages de doc | Cassent en local | Liens relatifs |
| H4+ pour structurer | Invisible dans la table des matieres | Restructurer en H2/H3 |
Previsualisation et validation¶
Serveur local¶
pip install mkdocs-material
mkdocs serve
Le site est accessible sur http://127.0.0.1:8000 avec rechargement automatique.
Points de verification¶
| Verification | Comment |
|---|---|
| Build sans erreur | mkdocs build --strict |
| Navigation | Verifier que toutes les pages sont accessibles via le menu |
| Rendu Mermaid | Ouvrir chaque page contenant un diagramme |
| Tooltips glossaire | Survoler un terme technique |
| Mobile | Reduire la fenetre pour verifier le responsive |