Documenter, c'est écrire le document dont un lecteur précis a besoin, au moment où il en a besoin, et le garder juste aussi longtemps que ce qu'il décrit existe. Cette page ouvre la formation Documenter, une formation transverse : elle sert l'administrateur, le développeur, le SRE et l'architecte. Elle vous fait choisir le bon document, l'écrire clair, le schématiser en code, le faire vivre dans Git, puis la publier en site statique. C'est une vraie compétence, trop souvent laissée au hasard.
Pourquoi apprendre à documenter ?
Section intitulée « Pourquoi apprendre à documenter ? »Une documentation absente coûte cher au pire moment, et une documentation fausse coûte encore plus cher, parce qu'on lui fait confiance. Il est 2 h du matin, l'alerte tombe sur le service de paiement, et la seule personne qui sait le redémarrer est en vacances. Le wiki est muet, les messages de 2022 contredisent le code. Ce scénario n'est pas un manque de bonne volonté : c'est un manque de méthode.
La méthode tient en quelques gestes qui s'apprennent : savoir pour qui on écrit, écrire pour être lu sous pression, ranger la documentation avec le code qu'elle décrit, lui donner un propriétaire et la faire vérifier par une machine. C'est ce que cette formation enseigne, sans vous imposer un outil.
À qui sert cette formation ?
Section intitulée « À qui sert cette formation ? »Elle s'adresse à celles et ceux qui écrivent déjà « un peu », un README, une page de wiki, une procédure, sans méthode pour le faire. Les admins et les SRE y trouvent de quoi écrire des procédures qui tiennent en incident, les développeurs de quoi documenter un dépôt et son code, les architectes de quoi tracer une décision et dessiner un système.
Les prérequis sont légers. Pour le premier niveau, il suffit de savoir
éditer un fichier texte et proposer une modification dans Git (un commit,
une pull request). Pour le second, il faut en plus savoir lancer une commande
npm ou pip, c'est-à-dire utiliser un gestionnaire de paquets.
Comment la formation est-elle organisée ?
Section intitulée « Comment la formation est-elle organisée ? »La formation se déroule en deux niveaux, chacun avec son résultat, et quelques modules facultatifs pour aller plus loin. Le programme détaillé, avec le suivi de votre progression, se trouve dans Mon parcours.
Niveau 1 : écrire une documentation utile
Section intitulée « Niveau 1 : écrire une documentation utile »Le premier niveau est le cœur de la formation. À son terme, vous livrez, pour un service que vous ne connaissiez pas, un README, un ADR, un diagramme C4 en code et une page pratique que quelqu'un d'autre peut suivre, et vous savez relire une page pour en lister les défauts.
- Pourquoi et pour qui documenter : ce que coûte l'absence de documentation, puis le geste fondateur, choisir le bon document (tutoriel, guide, référence ou explication) d'après son lecteur.
- Le module Écrire : écrire clair, Markdown (et AsciiDoc en facultatif), montrer plutôt qu'écrire, le README et le CHANGELOG, l'ADR et la documentation du code.
- Schématiser : le modèle C4, puis les diagrammes écrits en code (Mermaid, D2), lisibles même sans l'image.
- Faire vivre la documentation : la documentation dans Git, un propriétaire par document, des revues planifiées et les anti-patterns qui la tuent.
Niveau 2 : outiller et publier
Section intitulée « Niveau 2 : outiller et publier »Le second niveau publie la documentation en site statique. Il commence par choisir un générateur, puis construit un site avec Astro Starlight, le fil rouge du niveau. MkDocs, Docusaurus, Hugo et Antora sont proposés en facultatif, pour comparer.
Les modules facultatifs
Section intitulée « Les modules facultatifs »Deux modules complètent les niveaux sans être exigés. Documents d'exploitation réunit les documents qui servent en production, runbooks, checklists, fiches de service et postmortems, partagés avec la formation Exploitation des serveurs. Présenter montre comment écrire des présentations techniques en Markdown, versionnées comme la documentation, avec Slidev ou Reveal.js.
Comment les acquis se valident-ils ?
Section intitulée « Comment les acquis se valident-ils ? »Chaque leçon se termine par un quiz. Le quiz vérifie que vous avez compris la leçon : il est tiré d'une banque, si bien que deux tentatives ne posent pas les mêmes questions.
Le geste lui-même se pratique sur vos propres documents : ceux d'un service que vous ne connaissiez pas pour le premier niveau, puis votre site publié pour le second.
Par où commencer selon votre situation ?
Section intitulée « Par où commencer selon votre situation ? »Si vous partez de rien, suivez le premier niveau dans l'ordre : chaque module s'appuie sur le précédent. Si une urgence vous amène, trois entrées directes existent.
- Un incident vous a pris au dépourvu : commencez par les runbooks, puis revenez au premier niveau pour que la procédure reste juste.
- Un dépôt n'a pas de porte d'entrée : commencez par le README et le CHANGELOG.
- Personne ne sait plus pourquoi un choix a été fait : commencez par l'ADR.
À retenir
Section intitulée « À retenir »- Documenter est une compétence qui s'apprend, transverse à tous les métiers techniques.
- Le premier niveau apprend à choisir, écrire, schématiser et faire vivre une documentation.
- Le second niveau la publie en site statique.
- Documents d'exploitation et Présenter sont facultatifs.
- Chaque leçon se valide par un quiz.