Meilleures pratiques Markdown pour la documentation logicielle
Rédigez une meilleure documentation technique grâce à ces modèles et conventions Markdown éprouvés, utilisés par les meilleures équipes d'ingénierie.
Jacky
Une bonne documentation est aussi importante qu'un bon code. Markdown est devenu le format standard pour la documentation technique sur GitHub, GitLab, Confluence et d'innombrables autres plateformes. Voici les modèles utilisés par les meilleures équipes d'ingénierie.
Structurez vos documents
Chaque document doit avoir une hiérarchie claire. Utilisez un seul # H1 pour le titre, puis ## H2 pour les sections principales et ### H3 pour les sous-sections.
# API Reference
## Authentication
### API Keys
### OAuth 2.0
Ne sautez jamais de niveaux de titres — passer de ## à #### perturbe aussi bien les lecteurs que les lecteurs d'écran.
Les blocs de code sont incontournables
Spécifiez toujours le langage pour les blocs de code. Cela active la coloration syntaxique et indique aux lecteurs ce qu'ils regardent :
```python
def greet(name: str) -> str:
return f"Hello, {name}!"
```
Pour les commandes de terminal, utilisez bash ou sh. Pour les fichiers de configuration, utilisez le format approprié (yaml, toml, json).
Documentez les sorties de commandes
Lorsque vous documentez des outils CLI, montrez à la fois la commande ET sa sortie attendue :
```bash
$ git status
On branch main
nothing to commit, working tree clean
```
Utilisez des tableaux pour les options de configuration
Les tableaux sont parfaits pour documenter les paramètres de configuration :
| Option | Type | Défaut | Description |
|---|---|---|---|
host | string | localhost | Nom d'hôte du serveur |
port | number | 3000 | Port d'écoute |
debug | boolean | false | Activer la journalisation de débogage |
Encadrés pour les informations importantes
De nombreuses plateformes prennent en charge la syntaxe callout/admonition. Utilisez des citations comme solution de repli :
> **Note:** This feature requires Node.js 18 or later.
> **Warning:** This operation is irreversible.
Gardez la documentation maintenable
- Utilisez des liens relatifs pour les références de documentation interne
- Conservez les fichiers image dans un répertoire dédié
docs/images/ - Incluez une date de « Dernière mise à jour » dans les documents à longue durée de vie
- Divisez les documents très longs en fichiers plus petits liés entre eux
Versionnez votre documentation avec votre code
La documentation vit dans le même dépôt que le code qu'elle décrit. Cela garantit que la documentation reste synchronisée avec les versions et peut être revue dans la même pull request que les modifications de code.