Choisir le bon document : tutoriel, guide pratique, référence ou explication

25 min
Quiz · 6 questions

Par Stéphane Robert mis à jour le 13 octobre 2026

Améliorer cette page

Que voulez-vous signaler ?

L’issue s’ouvre déjà remplie avec le titre et l’adresse de cette page.

Avant d'écrire, on se demande de quel type est le document, car chaque type sert un lecteur différent et s'écrit autrement. Le cadre Diátaxis en distingue quatre : le tutoriel (apprendre en faisant), le guide pratique (atteindre un but), la référence (consulter un fait) et l'explication (comprendre le pourquoi). Deux questions suffisent pour trancher : le contenu guide-t-il une action ou apporte-t-il une connaissance, et le lecteur étudie-t-il ou travaille-t-il ? Cette leçon apprend à poser ces deux questions sur une demande réelle, à en déduire un plan, et à reconnaître une page qui mélange deux types.

Ce que vous allez apprendre

Classer une demande de documentation avec les deux questions de la boussole Diátaxis
Déduire d'un type son lecteur, son plan et ce qu'on n'y met pas
Situer une décision (ADR) et une procédure d'exploitation (runbook) par rapport aux quatre types
Réécrire le plan d'une page qui mélange guide pratique et explication

Aucun prérequis technique : savoir éditer un fichier texte suffit. La leçon Pourquoi documenter est vital ? donne les raisons de documenter ; celle-ci apprend à choisir quoi écrire.

Pourquoi une page « complète » finit-elle par ne servir personne ?

Une page qui essaie de tout dire échoue pour une raison simple : ses lecteurs n'arrivent pas dans le même état d'esprit. Quelqu'un qui découvre un outil veut être guidé sans être noyé sous les options. Quelqu'un qui travaille et connaît l'outil veut la commande exacte, tout de suite. Une personne qui cherche à comprendre une architecture veut un récit, pas une liste d'étapes. Une même page ne peut pas leur parler à tous en même temps.

Le cadre Diátaxis, publié sur diataxis.fr, part de ce constat. Il ne s'agit pas d'une norme à appliquer à la lettre : c'est une grille de lecture qui aide à repérer, dans un texte ou dans une demande, ce que le lecteur attend. Ses quatre types se déduisent de deux axes.

Quels sont les deux axes et les quatre types ?

Les deux axes se résument en deux oppositions. La première sépare l'action (des étapes pratiques, ce qui se fait) de la cognition (un savoir théorique, ce qui se sait). La seconde sépare l'acquisition (le lecteur étudie pour apprendre) de l'application (le lecteur travaille et veut accomplir une tâche). Ces quatre mots sont ceux de la page « The compass » du site Diátaxis. Leur croisement donne quatre cases, que le schéma ci-dessous parcourt sous forme de décision.

Regardez le schéma de haut en bas : la première question sépare l'action de la connaissance, la seconde sépare l'étude du travail. Les deux réponses mènent à un seul type. Les deux losanges portent la même question, mais elle ne mène pas au même résultat selon la branche d'où l'on vient.

Les deux questions de la boussole Diátaxis et les quatre types de document auxquels elles mènent. Source · SVG

Le tableau ci-dessous donne la même règle sous forme de correspondance : un contenu qui guide l'action au service de l'acquisition est un tutoriel ; au service de l'application, un guide pratique. Un contenu qui apporte une connaissance au service de l'application est une référence ; au service de l'acquisition, une explication. Ces deux questions servent surtout quand on doute, et se posent aussi bien à un document entier qu'à une simple phrase.

Type	Le contenu...	...au service de	Le lecteur veut
Tutoriel	guide une action	l'acquisition d'une compétence	apprendre en faisant
Guide pratique	guide une action	l'application de la compétence	atteindre un but précis
Référence	apporte une connaissance	l'application de la compétence	consulter un fait fiable
Explication	apporte une connaissance	l'acquisition d'une compétence	comprendre pourquoi

Que contient chaque type, et qu'est-ce qu'on n'y met pas ?

Chaque type se définit autant par ce qu'il exclut que par ce qu'il contient. Presque tous les défauts de documentation viennent d'un morceau d'un type glissé dans un autre. Pour chaque type, voici le lecteur, un plan type et ce qu'on y laisse de côté. Ces plans sont des points de départ : le projet The Good Docs Project propose des gabarits prêts à remplir.

Le tutoriel

Le tutoriel est une leçon : le lecteur apprend en réalisant quelque chose de concret, sous la conduite de l'auteur, et en ressort avec la confiance qu'il sait le faire. Son lecteur est un apprenant, en pratique souvent un débutant qui fait des choses nouvelles qu'il ne comprend pas encore entièrement, et le résultat compte moins que la confiance gagnée.

Plan type : l'objectif concret, ce qu'on aura obtenu à la fin, les étapes numérotées avec le résultat visible après chacune, la vérification finale.
On n'y met pas : les explications longues, les options, les cas particuliers. On renvoie vers l'explication ou la référence au lieu de les inclure.

Le guide pratique

Le guide pratique est une marche à suivre pour atteindre un but précis, comme configurer une rotation de secrets. Son lecteur connaît déjà les bases et veut finir son travail correctement. Un bon guide porte sur un problème du lecteur (« renouveler un secret »), pas sur une fonctionnalité de l'outil (« les commandes de vault »).

Plan type : le but en une phrase, les prérequis, les étapes numérotées, la vérification, un retour arrière si le geste est risqué.
On n'y met pas : l'histoire de l'outil, le pourquoi détaillé, la liste exhaustive des options. On les lie.

La référence

La référence décrit la machinerie : commandes, paramètres, variables, codes d'erreur, points d'API. Son lecteur la consulte plus qu'il ne la lit, au milieu d'une tâche, et exige une information exacte et complète.

Plan type : une structure identique pour chaque entrée (nom, type, valeur par défaut, description courte, exemple), classée dans un ordre prévisible (alphabétique, ou calqué sur le produit).
On n'y met pas : le mode d'emploi pas à pas, les opinions, les conseils. Les exemples restent courts et servent à illustrer, pas à guider.

L'explication

L'explication donne du contexte : pourquoi les choses sont ainsi, quelles alternatives existaient, comment les éléments s'articulent. Son lecteur réfléchit : il n'a pas besoin du produit sous les yeux, et peut la lire loin du clavier.

Plan type : le sujet délimité, le contexte, le raisonnement, les alternatives et leurs limites, les liens vers les autres pages.
On n'y met pas : des étapes à exécuter, des listes de paramètres. Une commande n'y apparaît que pour illustrer une idée.

Et la décision, et la procédure d'exploitation ?

Diátaxis couvre les quatre types ci-dessus et rien d'autre. Or deux documents de DevOps ne rentrent pas proprement dans les cases : la décision et la procédure d'exploitation. Cette formation les traite à part, mais il est utile de dire comment ils se rattachent aux quatre types. Ce rattachement est un choix de lecture propre à cette formation, pas une règle du cadre.

La décision (un ADR, Architecture Decision Record) répond à « pourquoi a-t-on choisi cela ? ». Par son contenu, elle est proche de l'explication : elle apporte une connaissance et son lecteur cherche à comprendre. Elle s'en distingue par sa vie : un ADR est daté, court et figé une fois accepté, là où une explication se réécrit quand le sujet évolue. La leçon Architecture Decision Records en détaille le format, plus loin dans le parcours.

La procédure d'exploitation (un runbook) répond à « que fait-on quand cette alerte sonne ? ». Par son contenu, c'est un guide pratique : action au service du travail. Elle s'en distingue par son contexte de lecture : son lecteur est pressé, parfois réveillé en pleine nuit, et ne doit rien avoir à interpréter. Elle est donc plus courte, plus directive, et rattachée à un déclencheur précis. Le module facultatif sur les runbooks s'y consacre, et la page Documentation opérationnelle montre comment ranger ces documents pour les retrouver.

Comment s'entraîner : classer dix demandes réelles

Le geste se travaille par la pratique. Dans le tableau suivant, chaque ligne est une demande telle qu'un collègue pourrait la formuler. Avant de lire la colonne de droite, posez-vous les deux questions : action ou connaissance ? le lecteur étudie-t-il ou travaille-t-il ? Notez votre réponse, puis comparez.

#	Demande	Type	Justification
1	« Comment ajouter un utilisateur au VPN ? »	Guide pratique	Un but précis, un lecteur qui sait déjà administrer le VPN et travaille.
2	« La liste des variables d'environnement du service »	Référence	Un fait à consulter, exhaustif, sans récit.
3	« Pourquoi a-t-on choisi PostgreSQL plutôt que MySQL ? »	Décision (ADR)	Un choix daté à tracer avec ses options écartées ; le contenu est celui d'une explication.
4	« Un parcours pour déployer sa première application sur le cluster, pour les nouveaux arrivants »	Tutoriel	Le lecteur apprend en faisant ; le but est la montée en compétence, pas l'application déployée.
5	« Que faire quand l'alerte "disque plein sur db-01" sonne à 3 h du matin ? »	Procédure d'exploitation (runbook)	Action, lecteur pressé, déclencheur précis.
6	« Comment fonctionne notre stratégie de sauvegarde, et pourquoi la règle 3-2-1 ? »	Explication	Connaissance, raisonnement, pas d'étapes à exécuter.
7	« Toutes les options de notre CLI interne `deployctl` »	Référence	Description exhaustive de la machinerie.
8	« Comment renouveler un secret de base de données ? »	Guide pratique	Un problème du lecteur, avec des étapes et une vérification.
9	« Apprendre à écrire sa première règle d'alerte, pour un nouvel arrivant dans l'équipe d'astreinte »	Tutoriel	Un exercice guidé avec un résultat visible à chaque étape.
10	« Qu'est-ce que l'idempotence, et pourquoi nos rôles la respectent ? »	Explication	Un concept à comprendre, sans commande à exécuter.

Les lignes 3 et 5 sont les plus instructives : les deux questions les rangent dans les cases « explication » et « guide pratique », mais elles appellent un format propre, d'où la place à part que leur donne la formation. Les lignes 1 et 8 ressemblent aux lignes 4 et 9 (toutes décrivent des étapes) : ce qui les départage est le lecteur. Il sait déjà (guide pratique), ou il apprend (tutoriel).

Comment repérer une page qui mélange deux types ?

Une page mélangée se reconnaît à un symptôme : on ne sait pas à quelle question elle répond. En lisant le plan, repérez les titres qui relèvent de types différents, puis appliquez la boussole à chaque section. Voici le plan type d'une page de ce genre, intitulée « Déployer l'API avec Helm » :

1. Pourquoi nous avons choisi Helm
2. Prérequis
3. Déployer l'API en recette
4. Pourquoi un fichier values par environnement
5. Liste de tous les paramètres du chart
6. Si le déploiement échoue

Les sections 2, 3 et 6 sont un guide pratique : un but, des étapes, un dépannage. Les sections 1 et 4 sont de l'explication : le pourquoi d'un choix. La section 5 est de la référence : une liste à consulter. Le lecteur pressé de déployer doit enjamber deux sections de justification pour arriver aux étapes, et celui qui veut comprendre le choix de Helm cherche son chemin au milieu des commandes.

Le schéma relie chaque section de la page d'origine à la page qui la reçoit : trois pages, chacune d'un seul type, et deux liens depuis le guide vers ce qu'on lui a retiré.

Source · SVG

La réécriture éclate la page en deux, et déplace la liste de paramètres vers une référence :

Guide pratique : Déployer l'API en recette
  1. Prérequis
  2. Étapes de déploiement
  3. Vérifier le déploiement
  4. Revenir en arrière
  5. Si le déploiement échoue
  -> liens : « Pourquoi Helm et un values par environnement »,
     « Paramètres du chart »

Explication : Pourquoi Helm et un fichier values par environnement
  1. Le problème de départ
  2. Les alternatives écartées
  3. Ce que ce choix coûte
  -> lien : « Déployer l'API en recette »

Référence : Paramètres du chart (une entrée par paramètre : nom, type,
valeur par défaut, description)

Ce qu'on retire du guide, c'est tout ce qui n'aide pas à exécuter : les sections 1 et 4. Elles ne disparaissent pas, elles quittent la page où elles gênaient pour devenir une explication à part, que le guide lie en une phrase. La section 5 devient une référence, qui peut d'ailleurs être générée à partir du chart (la page Qualité des charts Helm montre cette génération avec helm-docs).

Où trouver des gabarits prêts à remplir ?

Écrire un plan à chaque fois est coûteux, et un gabarit évite d'oublier une section. The Good Docs Project (thegooddocsproject.dev) maintient des gabarits ouverts, accompagnés de guides d'usage. Son pack de base propose notamment un gabarit Concept (une explication), un gabarit How-to (une suite d'étapes numérotées pour une tâche), un gabarit Reference (la description de composants ou de caractéristiques), un gabarit Tutorial (la mise en place d'un exemple, pour apprendre en pratiquant), mais aussi README, Release notes et Troubleshooting. Ces noms recoupent nettement les quatre types Diátaxis.

Un gabarit n'est pas un contrat : on le prend comme liste de contrôle, on supprime les sections inutiles et on garde l'esprit du type. Garder les gabarits dans un dossier versionné avec le code rend leur copie et leur relecture naturelles : c'est le principe de Docs as code, vu plus loin dans cette formation. Pour écrire les fichiers eux-mêmes, le guide Markdown suffira.

Quels sont les pièges les plus fréquents ?

Trois défauts reviennent presque toujours, et chacun se corrige en appliquant la boussole à la page fautive.

Le README fourre-tout mélange présentation du projet, installation pas à pas, liste de configuration, choix d'architecture et historique. Il est lu par des gens très différents : un nouveau venu, un contributeur, un exploitant. Le remède consiste à garder dans le README ce qui oriente (que fait le projet, comment le lancer en une commande) et à renvoyer chaque reste vers une page de son type.

Le tutoriel qui explique tout interrompt chaque étape par un paragraphe de théorie. Le débutant perd le fil de l'action, et les explications ne restent pas, car il n'a pas encore de quoi les accrocher. Le remède consiste à n'expliquer que le strict minimum pour avancer, et à lier l'explication complète.

La référence qui raconte ajoute des conseils, des anecdotes et des recommandations entre deux entrées. Le lecteur qui consulte cherche une donnée précise et veut la trouver en dix secondes. Le remède consiste à déplacer les conseils vers un guide ou une explication, et à garder des entrées de forme identique, sèches et complètes.

À retenir

Quatre types de document, deux questions pour choisir : le contenu guide-t-il une action ou apporte-t-il une connaissance, et le lecteur étudie-t-il ou travaille-t-il ?
Tutoriel : apprendre en faisant. Guide pratique : atteindre un but. Référence : consulter un fait. Explication : comprendre le pourquoi.
Chaque type a un lecteur, un plan et des exclusions : ce qu'on n'y met pas compte autant que ce qu'on y met.
Dans cette formation, la décision (ADR) se range près de l'explication et la procédure d'exploitation (runbook) près du guide pratique, avec un format propre. Ce rattachement n'est pas dans Diátaxis.
Une page qui répond à plusieurs questions se scinde en pages liées entre elles, au lieu de faire patienter le lecteur.
Les gabarits de The Good Docs Project servent de liste de contrôle, pas de contrat.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

Le chronomètre démarre au clic sur Démarrer
Questions à choix multiples, vrai/faux et réponses courtes
Vous pouvez naviguer entre les questions
Les résultats détaillés sont affichés à la fin