Types de documentation : tutoriels, guides pratiques, références et explications

Choisissez le bon type de documentation pour chaque page en utilisant le framework Diátaxis : tutoriels, guides pratiques, référence et explication.

Toute la documentation ne sert pas le même objectif. Un tutoriel qui accompagne un nouvel utilisateur lors de son premier déploiement est fondamentalement différent d’une référence API qu’un développeur consulte chaque jour. Mélanger ces objectifs dans une seule page crée un contenu qui ne remplit bien aucun des deux rôles.

Le framework Diátaxis fournit un système pratique pour catégoriser la documentation selon le besoin de l’utilisateur à un moment donné.

​

Les quatre types de documentation

​

Tutoriels (orientés apprentissage)

Les tutoriels enseignent par la pratique. L’objectif de l’utilisateur est d’apprendre quelque chose de nouveau, et l’objectif du tutoriel est de lui offrir une expérience réussie — pas de documenter chaque option ni d’expliquer chaque détail.

Un bon tutoriel :

• Ne suppose aucune connaissance préalable de la tâche spécifique
• Accompagne l’utilisateur à travers un exemple complet et fonctionnel du début à la fin
• Minimise les choix — dites aux utilisateurs exactement quoi faire plutôt que de proposer des alternatives
• Marque la progression à des étapes significatives (“Vous avez maintenant configuré l’authentification”)
• Explique juste assez pour maintenir l’utilisateur en mouvement, pas tout ce qu’il y a à savoir

Les tutoriels sont le type de contenu qui demande le plus d’investissement à rédiger et à maintenir, mais ils ont un impact démesuré sur la réussite des nouveaux utilisateurs avec votre produit.

​

Guides pratiques (orientés tâches)

Les guides pratiques aident les utilisateurs à accomplir un objectif spécifique. Contrairement aux tutoriels, ils supposent que l’utilisateur a déjà un certain contexte et veut faire quelque chose de particulier, pas apprendre un concept.

Un bon guide pratique :

• Traite une tâche spécifique dans le titre et tout au long du contenu
• Suppose une connaissance préalable des prérequis
• Fournit une séquence claire d’étapes sans contexte inutile
• Décrit quoi faire, pas comment le système fonctionne en dessous

La distinction avec les tutoriels est importante en pratique : un tutoriel sur “Premiers pas avec l’authentification” accompagne un nouvel utilisateur à travers tout le processus étape par étape. Un guide pratique sur “Effectuer la rotation de vos clés API” suppose que l’utilisateur sait ce que sont les clés API et a juste besoin des étapes.

​

Référence (orientée information)

La documentation de référence décrit le système de manière précise et complète. Les utilisateurs la consultent pour chercher quelque chose — ils ne lisent pas de manière séquentielle et ne sont pas en train d’apprendre.

Une bonne documentation de référence :

• Priorise l’exhaustivité et la précision avant tout
• Est parcourable : tableaux, formatage cohérent, descriptions courtes
• Évite le contenu explicatif ou conceptuel
• Documente tout, y compris les valeurs par défaut, les limites et les cas limites
• Reste proche de la structure de ce qui est documenté (une référence API suit la structure de l’API)

Les références API, les listes d’options de configuration et les références de commandes CLI sont tous du contenu de référence.

​

Explication (orientée compréhension)

Les explications approfondissent la compréhension d’un concept. Les utilisateurs les lisent quand ils veulent comprendre pourquoi quelque chose fonctionne de telle manière, pas comment effectuer une tâche spécifique.

Un bon contenu d’explication :

• Aborde le contexte et la motivation derrière une décision de conception
• Reconnaît les compromis et les alternatives
• Relie les concepts à travers le système plus large
• Est à l’aise pour être opiniâtre quand c’est approprié

Les vues d’ensemble d’architecture, les guides de concepts et les pages “comment fonctionne X” sont tous du contenu d’explication. Ils se distinguent des guides pratiques en ce qu’un lecteur terminant un article d’explication ne devrait pas avoir l’impression qu’on lui a dit de faire quelque chose — il devrait avoir l’impression de mieux comprendre quelque chose.

​

Choisir le bon type pour chaque page

Question	Tutoriel	Guide pratique	Référence	Explication
Quel est l’objectif de l’utilisateur ?	Apprendre par la pratique	Résoudre un problème spécifique	Trouver une information précise	Comprendre un concept
Quel est le niveau de connaissance de l’utilisateur ?	Débutant	Intermédiaire	Expérimenté	Tout niveau
Le contenu est-il orienté tâches ?	Oui, guidé	Oui, spécifique	Non	Non
Est-il séquentiel ?	Oui	Généralement	Non	Non

En cas de doute sur le type qui convient à une page, demandez-vous : “Que fait l’utilisateur après avoir lu ceci ?” S’il a accompli une tâche, c’est un guide pratique ou un tutoriel. S’il comprend maintenant quelque chose et peut passer à l’action ailleurs, c’est une explication. S’il a cherché un détail spécifique, c’est une référence.

​

Rédiger pour chaque type

​

Rédiger des tutoriels

Définissez les attentes au début : qu’est-ce que les utilisateurs auront construit ou accompli à la fin ? Utilisez les composants <Steps> pour la progression séquentielle et célébrez l’achèvement aux étapes naturelles. Minimisez les décisions — là où il existe plusieurs approches valides, choisissez-en une et dites-le.

​

Rédiger des guides pratiques

Commencez par la tâche dans le titre : “Comment configurer les webhooks”, “Comment migrer de v1 à v2”. Rédigez du point de vue de l’utilisateur, pas du produit. Omettez le contexte qui n’affecte pas les étapes. Créez des liens vers du contenu d’explication ou de référence pour les utilisateurs qui veulent en savoir plus.

​

Rédiger une référence

Structurez les documents de référence autour de ce qui est décrit, pas autour des parcours utilisateurs. Utilisez un formatage cohérent pour toutes les entrées. Chaque paramètre, flag ou option devrait avoir un type, une valeur par défaut et une description d’une ligne. Gardez-le parcourable.

​

Rédiger une explication

Commencez par la question à laquelle vous répondez : “Pourquoi l’authentification fonctionne-t-elle de cette façon ?” ou “Quelle est la différence entre les organisations et les espaces de travail ?” Reconnaissez que plusieurs approches existent et expliquez pourquoi le produit fait les choix qu’il fait. Créez des liens vers des guides pratiques pour les utilisateurs qui veulent agir sur ce qu’ils ont appris.

​

Conseils pour maintenir la cohérence des types

• Attribuez un type de contenu avant de rédiger. Décider à l’avance façonne toutes les autres décisions de rédaction : structure, longueur, ton, ce qu’il faut inclure et exclure.
• Révisez les pages à objectifs multiples. Les pages qui expliquent un concept, incluent un tutoriel et référencent une liste d’options en même temps sont difficiles à maintenir et à utiliser. Divisez-les ou choisissez un type principal.
• Adaptez le framework à votre produit. Diátaxis est un point de départ, pas une règle rigide. Les produits avec des structures inhabituelles peuvent nécessiter des approches hybrides. Le principe sous-jacent — faire correspondre le contenu au besoin de l’utilisateur à un moment donné — s’applique universellement.

​

Questions fréquemment posées

Ai-je besoin des quatre types de contenu pour chaque fonctionnalité ?

Non. Les petites fonctionnalités peuvent n’avoir besoin que d’un guide pratique et d’une entrée de référence. Les types décrivent des besoins que les utilisateurs pourraient avoir, pas une liste de vérification que vous devez compléter. Commencez par ce dont vos utilisateurs ont réellement besoin — généralement un guide pratique et une référence — et ajoutez des tutoriels et des explications là où les utilisateurs ont constamment du mal à démarrer ou à comprendre quelque chose.

Quelle est la différence entre un tutoriel et un guide pratique ?

Les tutoriels sont des expériences d’apprentissage. L’utilisateur commence sans connaissance et finit par avoir construit ou accompli quelque chose, le tutoriel faisant l’essentiel du travail pédagogique. Les guides pratiques sont des références de tâches. L’utilisateur sait ce qu’il veut faire et a besoin des étapes pour le faire. Un tutoriel sur “Construisez votre première intégration” et un guide pratique sur “Connecter une nouvelle intégration” peuvent couvrir des actions similaires mais servent des utilisateurs entièrement différents dans des contextes entièrement différents.

Une seule page peut-elle servir plusieurs types de contenu ?

En pratique, les pages mélangent souvent les types — surtout le contenu de démarrage qui combine tutoriel et guide pratique. La question est de savoir si le mélange sert les utilisateurs ou les déroute. Si une page doit à la fois enseigner un concept (explication) et accompagner la configuration (tutoriel), une structure de sections claire peut fonctionner. Si le contenu est trop mélangé pour être organisé proprement, le diviser en pages séparées produit généralement de meilleurs résultats.

Quel niveau de détail la documentation de référence doit-elle avoir ?

Suffisamment complète pour que les utilisateurs n’aient pas besoin de lire le code source ni de contacter le support pour comprendre un paramètre ou une option. Chaque valeur configurable devrait avoir une description, un type, une valeur par défaut et un exemple. La documentation de référence qui omet les cas limites ou les limitations oblige les utilisateurs à découvrir ces limites par essai et erreur — c’est un échec de la documentation, pas une erreur de l’utilisateur.

​

Pages associées

Modèles de contenu

Copiez et modifiez des modèles pour chaque type de contenu.

Style et ton

Rédigez une documentation efficace avec un style cohérent.

Comprendre votre audience

Recherchez et définissez l’audience de votre documentation.

Navigation

Organisez la structure de votre documentation efficacement.

Améliorer votre documentation

Utilisez les données et les métriques pour améliorer la documentation.