Rédiger une documentation technique propre tient souvent à peu de choses: un exemple lisible, un bloc de code stable et assez de contexte pour que le lecteur puisse copier-coller sans casser le rendu. La syntaxe de code Markdown règle ce problème, mais seulement si l’on choisit le bon format et si l’on garde quelques règles simples en tête. Je vais passer en revue les formes utiles, les cas où je privilégie les fences, les pièges à éviter et la méthode que j’applique quand j’écris pour des équipes produit ou backend.
Les repères utiles pour écrire du code proprement en Markdown
- Les blocs fermés par trois backticks sont le choix par défaut dans la plupart des docs modernes.
- Les blocs indentés existent encore, mais ils sont moins lisibles et plus faciles à casser.
- Le nom du langage après la fence améliore souvent la coloration syntaxique, sans garantir le même rendu partout.
- Une ligne vide avant et après le bloc aide à garder un Markdown propre et prévisible.
- Les erreurs les plus fréquentes concernent la fermeture du bloc, l’indentation et les backticks qui se retrouvent au mauvais endroit.
Pourquoi les blocs de code comptent dans une documentation technique
Dans une doc de développement, un bloc de code n’est pas un simple effet visuel. Il sert à distinguer ce qui est exécutable de ce qui est explicatif, à rendre un exemple plus rapide à lire et à limiter les ambiguïtés quand on passe d’un éditeur à un autre. Quand je rédige pour du JavaScript, du backend ou de la sécurité applicative, je traite ce bloc comme une petite promesse: il doit être clair, copiable et fidèle à l’intention.Le vrai enjeu n’est pas seulement l’affichage, c’est la fiabilité de la copie et la cohérence entre l’éditeur, le CMS et la plateforme finale. Un bon exemple fait gagner du temps en revue de code, réduit les questions inutiles et évite les interprétations hasardeuses. Une fois ce besoin posé, le choix de la syntaxe devient beaucoup plus rationnel.
La syntaxe de base à maîtriser
Markdown propose trois usages utiles dès qu’on parle de code: le code en ligne, le bloc fermé et le bloc indenté. Pour une commande courte dans une phrase, j’utilise le code en ligne avec un seul accent grave, par exemple git status. Pour plusieurs lignes, je préfère presque toujours une fence, c’est-à-dire une ligne d’ouverture et une ligne de fermeture composées d’au moins trois backticks ou, selon le moteur, de tildes.
Si l’exemple contient déjà des backticks, je bascule volontiers sur les tildes pour éviter les collisions visuelles. C’est un détail, mais il rend la relecture plus sereine quand on documente un snippet qui parle lui-même de Markdown ou d’une autre syntaxe avec des délimiteurs.
Le code en ligne pour une commande courte
Le code en ligne me sert quand je veux signaler un nom de commande, une variable ou une clé précise sans interrompre le rythme d’une phrase. Il reste discret, lisible, et il évite de surcharger le texte avec un bloc complet alors qu’un fragment suffit.
Si la chaîne à afficher contient déjà un accent grave, j’augmente le nombre de délimiteurs autour du texte. Le principe est simple: plus le contenu est “syntaxiquement chargé”, plus il faut être attentif au contournement.
Les blocs fermés par des backticks
Je pars presque toujours de cette forme. Elle est claire à la lecture, compatible avec la majorité des plateformes modernes et facile à copier dans une PR, une issue ou une page de documentation.
```js
const user = "Nora";
console.log(user);
```Dans cette variante, le nom du langage placé sur la première ligne agit comme un indice pour le moteur de rendu. L’effet exact dépend du support, mais l’intention reste utile partout: le lecteur comprend immédiatement qu’il s’agit d’un extrait JavaScript.
Les blocs indentés et leurs limites
La version indentée demande quatre espaces au début de chaque ligne, ou parfois une tabulation selon le moteur. Elle reste utile pour des documents hérités, mais je la trouve moins explicite à l’œil et plus fragile dès qu’un éditeur réorganise l’indentation.
npm install
npm run devJe la garde surtout pour des raisons de compatibilité ou pour relire des fichiers anciens. Pour une nouvelle documentation, les fences me paraissent généralement plus sûres.
Le langage de la première ligne
Quand je précise bash, json, sql ou js, je ne cherche pas l’effet gadget. Je veux surtout aider le lecteur à identifier le type de contenu en une seconde et, quand c’est possible, déclencher un surlignage syntaxique plus utile. GitHub Docs recommande d’ailleurs de laisser une ligne vide avant et après le bloc, parce que cela rend le Markdown source plus lisible et limite les surprises au moment du rendu.
Avec ces formes en tête, on peut maintenant choisir celle qui colle vraiment au contexte au lieu d’appliquer une règle uniforme à tout le document.
Choisir le bon format selon le contexte
Dans une documentation moderne, je pars presque toujours d’une fence. J’utilise le code en ligne pour les fragments très courts, les blocs fermés pour les exemples réels et l’indentation seulement quand le contexte l’impose. CommonMark définit une fence comme une suite d’au moins trois backticks ou tildes, sans les mélanger; c’est une base simple, mais suffisamment stable pour couvrir la plupart des cas courants.
Ce choix n’est pas qu’une préférence esthétique. Il détermine la vitesse de lecture, la facilité de copie et la résistance du texte quand il passe d’un moteur Markdown à un autre. Le tableau ci-dessous résume la logique que j’applique le plus souvent.
| Format | Syntaxe | Quand je l’utilise | Atout principal | Limite à garder en tête |
|---|---|---|---|---|
| Code en ligne | git status |
Commande, variable ou mot-clé dans une phrase | Très compact et fluide à lire | Inadapté aux exemples multilignes |
| Bloc fermé avec langage | ```js ... ``` |
Exemple JavaScript, Bash, JSON, SQL | Lisible, copiable, souvent mieux surligné | La coloration dépend du moteur de rendu |
| Bloc fermé sans langage | ``` ... ``` |
Extrait générique ou texte technique brut | Simple et portable | Moins expressif pour le lecteur |
| Bloc indenté | git status |
Fichiers hérités ou compatibilité ancienne | Syntaxe historique connue de longue date | Plus facile à casser à la réédition |
Cette hiérarchie me sert de règle simple: si le lecteur doit exécuter une ligne dans son terminal, je le montre en fence avec le bon langage; s’il doit juste reconnaître un appel de fonction au milieu d’une phrase, j’utilise le code en ligne. Le document reste plus léger, et l’intention de chaque exemple devient plus nette.
Écrire des exemples qui se lisent et se copient bien
Un bon bloc de code n’est pas forcément long; il doit surtout être utile. J’essaie de montrer un exemple minimal qui compile, qui s’exécute ou qui se copie sans nettoyage manuel. C’est particulièrement vrai en JavaScript et côté backend, où un snippet trop large cache souvent le point essentiel derrière des lignes périphériques.
Pour le JavaScript et le backend
Quand je documente une fonction, je privilégie un extrait centré sur une seule idée. Cela évite de mélanger la logique métier, les imports sans importance et le décor d’infrastructure.
```js
export function createToken(payload) {
return sign(payload, process.env.JWT_SECRET);
}
```Ce type d’exemple fonctionne parce qu’il met en avant l’intention: générer un jeton. Le lecteur voit tout de suite ce que fait le code, sans devoir traverser toute l’architecture d’une application pour comprendre un détail.
Pour le terminal et les scripts d’installation
Pour une commande de terminal, je garde des lignes courtes et séquentielles. Si l’enchaînement devient plus long, je préfère découper en étapes numérotées plutôt que de forcer un seul bloc opaque.
```bash
npm ci
npm run test
```Dans ce format, le lecteur comprend à la fois l’ordre d’exécution et le point de départ. Pour une doc d’équipe, c’est souvent plus efficace qu’un paragraphe explicatif qui mélange plusieurs actions.
Lire aussi : Plan de déploiement informatique - Évitez les incidents !
Pour le JSON, la configuration et les exemples d’API
Sur JSON, la précision syntaxique compte autant que le fond. Un espace manquant, une virgule superflue ou un mauvais guillemet suffisent à ruiner la crédibilité de l’exemple, donc je vérifie toujours le rendu final dans le moteur cible.
```json
{
"name": "api-docs",
"private": true
}
```Pour une API, j’aime aussi séparer la requête et la réponse dans deux blocs distincts quand c’est possible. Le lecteur voit alors ce qu’il doit lancer et ce qu’il doit attendre en retour, ce qui est beaucoup plus clair qu’un exemple compact mais confus.
Plus le bloc est concret, moins il laisse de place à l’interprétation; c’est justement là qu’apparaissent les erreurs les plus fréquentes.
Les erreurs qui cassent souvent le rendu
Les problèmes de rendu Markdown sont rarement spectaculaires. Ils tiennent souvent à un détail de ponctuation ou d’indentation, et c’est pour cela qu’ils passent vite en revue mais coûtent cher en relecture.
- Oublier la ligne de fermeture du bloc. Le symptôme est immédiat: tout ce qui suit bascule dans le code.
- Indenter seulement une partie des lignes dans un bloc indenté. Le moteur interprète alors le fragment de manière incohérente.
- Mélanger backticks et tildes dans la même fence. Avec ce format, il faut rester sur un seul type de délimiteur.
- Placer l’étiquette de langage au mauvais endroit. Elle va sur la première ligne du bloc ouvert, pas sur la fermeture.
- Ajouter du texte explicatif sur la même ligne que la fermeture. Cela crée des rendus imprévisibles selon les moteurs.
- Copier-coller un extrait avec des tabulations ou des espaces invisibles. C’est un classique dans les docs techniques, surtout après un passage par un éditeur de texte riche.
Un autre piège concerne le code qui contient lui-même des accents graves. Dans ce cas, j’augmente le nombre de délimiteurs autour du code en ligne ou je réécris l’extrait pour éviter l’ambiguïté. Ce n’est pas spectaculaire, mais cela évite des bugs de rendu qui apparaissent au pire moment, juste avant la publication.
La règle simple que j’applique avant de publier une doc
Quand je publie une documentation, je vérifie systématiquement trois choses: le bloc se copie sans retouche, le langage affiché correspond au contenu et le rendu reste propre sur la plateforme finale. C’est là que les habitudes de rédaction font la différence entre un exemple théorique et une vraie aide pour le lecteur.
- Je choisis les fences par défaut, sauf besoin de compatibilité hérité.
- Je laisse une ligne vide autour du bloc quand le moteur le tolère.
- Je spécifie le langage seulement s’il apporte une vraie valeur au lecteur.
- Je garde les exemples courts, centrés sur une seule idée et faciles à rejouer.
- Je teste le rendu sur la plateforme cible avant de considérer le texte terminé.
Si je devais résumer la bonne pratique en une phrase, ce serait celle-ci: un bon bloc de code ne doit pas seulement afficher du code, il doit permettre au lecteur de le comprendre et de l’utiliser sans hésitation. C’est ce niveau de précision qui rend une documentation vraiment utile.
