- Partant du principe que la documentation technique doit jouer des rôles différents selon la situation de l’utilisateur, Diátaxis est une approche qui organise ensemble le contenu, la structure et le format
- Elle répartit les besoins des utilisateurs en 4 catégories et les fait correspondre aux types de documents tutorials, how-to guides, technical reference, explanation
- Plus qu’un simple tableau de classification, elle se rapproche d’un framework de conception documentaire qui traite de ce qu’il faut écrire, de la manière de l’écrire et de l’endroit où le placer
- Elle permet aussi aux auteurs et aux mainteneurs d’évaluer plus facilement la qualité de la documentation, avec l’avantage d’être légère, intuitive et de ne pas imposer de mode d’implémentation particulier
- Comme le montrent les cas de Vonage, Gatsby et Cloudflare, elle peut servir de référence pratique aux équipes qui cherchent à améliorer la navigabilité de leur documentation et la structure de l’information
Les 4 types de documentation définis par Diátaxis
- Diátaxis est à la fois une manière de penser et une manière d’agir pour rédiger et exploiter de la documentation technique
- Le point de départ consiste à comprendre les besoins des utilisateurs de la documentation, à partir desquels sont dérivés des principes sur le contenu, l’architecture et le format
- Les besoins documentaires et les formats se divisent en 4 catégories
-
tutorials
-
how-to guides
-
technical reference
- explanation
- La documentation elle-même doit aussi être organisée autour de ces 4 besoins, et Diátaxis traite simultanément trois questions
- content : quoi écrire
- style : comment écrire
- architecture : comment organiser
-
Applicabilité pour les auteurs et les mainteneurs
- Diátaxis est une approche utile non seulement pour les utilisateurs de la documentation, mais aussi pour les auteurs et les mainteneurs
- légère et facile à comprendre
- intuitive à appliquer
- n’impose pas de contraintes d’implémentation
- fournit des principes de qualité permettant aux mainteneurs d’évaluer leur propre travail
- Ces principes sont présentés comme ayant été adoptés avec succès dans des centaines de projets de documentation
Exemples de projets de documentation concrets
- Greg Frileux de Vonage estime qu’avec Diátaxis, il a pu créer un ensemble de documentation interne apprécié des utilisateurs et facile à enrichir pour les contributeurs
- Gatsby a utilisé le framework Diátaxis comme ressource principale lors de la restructuration de sa documentation open source, en indiquant que les 4 domaines ont aidé à prioriser les objectifs utilisateurs de chaque type de document
- Cloudflare a pris Diátaxis comme référence d’architecture de l’information lors de la refonte de Cloudflare developer docs, et s’appuie sur ce framework pour déterminer où doivent être placés les nouveaux contenus
1 commentaires
Commentaires sur Hacker News
Même du point de vue de quelqu’un qui n’écrit pas professionnellement, l’intuition la plus importante et la plus fondamentale que j’en ai tirée, indépendamment des détails, est qu’il n’est pas nécessaire de tout dire exactement une seule fois.
Avant de tomber sur cette idée, je me compliquais la vie en pensant qu’un seul flux de texte devait faire office de « document complet ».
Le simple fait de comprendre qu’on peut présenter la même information de différentes manières selon les lecteurs aide énormément.
Comme le lecteur cherche le dénominateur commun entre les exemples, c’est moins ambigu que de l’expliquer avec un seul exemple.
Des auteurs comme Salomon dans les Proverbes bibliques utilisaient beaucoup cette technique.
Dans le résumé, on écrit « cet article évalue Y par rapport à Z et montre que X est vrai » ; dans l’introduction, on explique que le problème A est important à cause de B, mais que l’aspect X a été négligé, et qu’évaluer Y révèle, contrairement à Z, des défis réalistes ; puis on récapitule : « en résumé, Y est meilleur que Z à cause de X ».
Dans les travaux connexes aussi, on enchaîne en disant que l’approche Z a amélioré certaines choses, mais qu’elle n’est pas suffisante comme on le montrera plus loin, et dans chaque section on revient sans cesse au message central en le traitant à nouveau sous un autre angle.
Il y a deux semaines, nous avons appliqué ce framework à la documentation de Sequin, et le simple fait d’avoir une structure a été extrêmement appréciable.
Le flux de la documentation est désormais bien meilleur, et il est plus facile d’ajouter et de maintenir des documents parce que nous savons quoi mettre où.
Ironiquement, la documentation de Diátaxis elle-même est un peu difficile et verbeuse ; il m’a fallu plusieurs lectures pour vraiment saisir l’idée.
Pour l’expliquer à l’équipe, j’ai utilisé l’analogie d’un appareil de cuisine comme une cocotte-minute : d’abord, avec un quick start (tutoriel), on voit grosso modo comment passer de A à B ; ensuite, chercher comment préparer un plat précis qu’on aime relève du how-to ; si l’on a des questions de détail, on consulte la référence pour vérifier les temps de cuisson exacts selon le type de haricot ; et quand on veut savoir pourquoi la pression change le temps de cuisson ou comment fonctionnent les dispositifs de sécurité, on lit les explications.
Ce qui est drôle, c’est que notre documentation était complètement à l’envers et commençait par une explication du type « How Sequin Works ».
L’impulsion naturelle des ingénieurs est de commencer par expliquer le fonctionnement et pourquoi on l’a conçu ainsi, afin d’installer un modèle mental, mais les gens n’ont ni le temps ni la patience pour cela.
Il vaut mieux les acclimater à l’univers via le flux quick start → how-to → référence, puis, une fois qu’on a réellement gagné leur intérêt, les convaincre de l’approche avec les explications.
https://sequinstream.com/docs
Les docs deviennent souvent floues avec des absurdités du genre « expérience de synergie innovante », comme si l’entreprise avait honte d’admettre que son outil n’est qu’un outil, ou au contraire elles entrent dans des détails beaucoup trop précis avant d’aborder « pourquoi ce produit existe ».
En revanche, CDC revient plusieurs fois dans la documentation et j’ai dû chercher sa définition. J’ai implémenté du CDC plusieurs fois dans ma carrière, mais je n’étais pas familier avec l’acronyme.
Le flux relève en fin de compte du choix du lecteur ; de mon côté, mon cerveau fonctionne en voulant d’abord l’explication d’ensemble, puis en cherchant les how-to et les tutoriels.
Du point de vue d’un rédacteur technique, Diátaxis ressemble à DITA : https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/information-typing.html
Cela dit, ce type de système peut passer à côté de ce dont les utilisateurs ont réellement besoin.
Si la documentation technique n’est utilisée qu’à l’intérieur d’une plateforme de documentation, Diátaxis peut rester bien adapté longtemps ; mais si les mêmes informations peuvent, et doivent, être utilisées à plusieurs endroits comme l’UI, un portail de documentation ou une app mobile, il peut être nécessaire de découper l’information en fragments plus petits et de les assembler de différentes façons.
C’est ce qu’on appelle la réutilisation de contenu, c’est-à-dire l’utilisation du même contenu à plusieurs emplacements.
L’une des approches de rédaction et d’édition de l’information pour la réutilisation de contenu est décrite dans le concept « every page is page one » : https://everypageispageone.com/the-book/
Si vous avez les ressources et le temps, je recommande de mener de la recherche UX au début du projet. Cela permet d’éviter de se retrouver plus tard étouffé par un modèle d’information trop restrictif.
Nielsen/Norman a aussi beaucoup travaillé sur ce domaine et propose des pistes intéressantes pour résoudre les problèmes associés : https://www.nngroup.com/articles/information-foraging/#toc-what-is-information-foraging-2
DITA distingue des types de sujets comme tâche, référence et concept, mais les tutoriels ou les guides de solution deviennent des combinaisons de ces types de sujets.
Ici, l’accent semble porter sur des livrables plus larges que les sujets individuels.
Je me demande aussi si le fait d’être très investi dans DITA rend sa complexité moins problématique.
Découper le contenu en fragments réutilisables et les baliser avec la sémantique DITA ou DocBook devrait, me semble-t-il, faciliter nettement la « compréhension » par les grands modèles de langage, mais je n’ai pas vu de données à ce sujet.
Aujourd’hui, il existe de meilleures façons d’écrire de la documentation que de s’acharner sur XSL/FO et ses cousins.
Dans le domaine de la rédaction de documentation technique, c’est déjà très populaire et assez proche d’un standard
Cela dit, certains poussent l’idée trop loin et finissent par ne mettre littéralement que ces quatre catégories sur les pages de documentation, ce qui ne fonctionne généralement pas très bien
C’est surtout utile pour aider l’auteur à garder en tête des idées du type « c’est un guide, donc n’essayons pas d’enseigner, concentrons-nous sur l’obtention du résultat »
Dans la réalité, des frontières trop rigides ne sont pas souhaitables, et ce n’est pas grave s’il y a un peu de tutoriel dans un guide
À mon avis, là où cette approche coince réellement, c’est quand les liens entre les quadrants sont insuffisants
Par exemple, dans un framework logiciel, si un guide ne renvoie pas vers la référence des classes ou méthodes précises qu’il faudra finalement utiliser, il devient beaucoup plus difficile d’explorer le contexte autour
Certaines documentations de frameworks bien précises ont séparé les quadrants de cette manière, et c’est l’une des choses les plus agaçantes dans ces documentations
S’il n’y a pas d’autre expert, un débutant peut avoir intérêt à suivre strictement les règles plutôt qu’à « faire ce qu’il faut par lui-même »
Par définition, un débutant n’a pas l’expertise nécessaire pour porter ce jugement, et avec l’expérience il commence à voir où il faut s’écarter des règles établies
C’est un peu comme la différence entre cuisiner à la maison en suivant un livre de recettes et un chef professionnel qui jette des ingrédients dans une casserole au feeling et au goût
Mais j’ai déjà travaillé avec quelqu’un qui soutenait qu’un tutoriel ne devait pas contenir une seule phrase d’explication et qu’il fallait suivre les règles à la lettre
Le risque de ce genre de système est précisément là
C’est comparable à des principes de programmation comme « ne modifiez pas les variables globales » ou « écrivez des fonctions courtes »
Il n’est pas nécessaire d’y parvenir parfaitement, mais la plupart du temps il vaut mieux aller dans cette direction que dans la direction opposée
J’ai donc demandé à Claude de classer la section du haut selon Diátaxis, et il a répondu qu’elle était principalement explicative, avec quelques éléments de référence, et qu’elle n’était pas idéale au regard de Diátaxis
Il a dit qu’il vaudrait mieux la diviser en une section expliquant purement le concept et l’importance de l’ajustement des hyperparamètres, et une section de référence séparée listant les outils et méthodes disponibles
Mais il a ensuite aussi résumé pourquoi cette approche intégrée fonctionne bien dans le contexte d’un guide utilisateur : elle suit le parcours réel d’apprentissage des gens, relie directement les concepts à leur implémentation, dévoile progressivement les choses des notions de base vers les outils complexes, et apporte une valeur pratique en reliant théorie et pratique
Ayant tout juste terminé la sortie de ma première app SwiftUI, j’ai fortement le sentiment que, dans l’industrie tech moderne, la documentation est traitée avec beaucoup trop de négligence
Le travail des excellents rédacteurs techniques qu’Apple a licenciés me manque énormément, et les ingénieurs d’Apple écrivent vraiment très mal la documentation
Cela dit, je me méfie toujours des approches « dogmatiques ». Il est facile de voir apparaître une « caste sacerdotale » qui refuse de plier même quand la réalité l’exige
Les personnes qui ont créé la doctrine au départ l’utilisent brillamment, mais les « prêtres » qui suivent peuvent la ruiner et transformer l’approche en malédiction
Beaucoup de bonnes idées ont été gâchées par des applications trop rigides. Il suffit de voir ce qu’est devenu « Agile »
La documentation a fondamentalement deux visages, celui des mainteneurs et celui des utilisateurs, et leurs besoins sont très différents ; il faudrait donc probablement qu’ils soient pris en charge par des équipes complètement distinctes
Il y a aussi le problème des documentations situées à plusieurs endroits qui finissent par se désynchroniser, mais ce qui compte, c’est le résultat
Si l’on peut synchroniser efficacement plusieurs instances, la documentation est efficace et utile pour les consommateurs
Même une documentation parfaitement formatée et synchronisée n’a aucune valeur si personne ne la lit
Dans SNL, The Anal-Retentive Chef, interprété par Phil Hartman, passait tellement de temps à préparer qu’il n’arrivait jamais à faire la démonstration de cuisine elle-même ; je vois souvent la même chose dans la tech
Les toolchains et les bibliothèques peuvent être parfaites, mais inutilisables en pratique
La documentation est un mélange de nature humaine et de psychologie, de design graphique, d’architecture de l’information, d’infrastructure technique, de publication et de distribution, entre autres domaines
Dans la plupart des projets, la documentation est traitée comme une réflexion après coup, mais je pense qu’elle devrait être une préoccupation de premier ordre dès la phase de définition des exigences
On peut creuser indéfiniment la structure de la documentation, mais jusqu’à ce qu’on trouve les points de fuite, cela joue très bien le rôle de petites roues
Cela donne l’impression que les malentendus courants ou les mauvaises applications d’une bonne idée abîmeraient l’idée elle-même
Au contraire, il y a de l’expérience à tirer de la mise en pratique. Si l’idée initiale n’était en fait pas bonne, cela dissipe l’illusion ; et les mauvais exemples, lorsqu’une mauvaise interprétation mène à l’échec, révèlent des ambiguïtés et permettent de rendre l’idée plus précise
Cela dit, si beaucoup de gens s’habituent à de mauvaises implémentations, la popularité de l’idée peut baisser, tout comme la demande pour des implémentations plus raffinées
C’est moins une dégénérescence de l’idée elle-même qu’une tragédie des anti-communs
Diátaxis est excellent pour structurer la documentation, mais sa vraie valeur est de simplifier la façon d’écrire la documentation
Il aide à sortir de l’idée qu’il faut tout entasser dans une seule « documentation parfaite » et à reconnaître que les besoins diffèrent selon les utilisateurs
Les tutoriels servent à apprendre en suivant pas à pas, les guides à résoudre des problèmes précis, les références à consulter rapidement, et les explications à creuser le « pourquoi »
Cette clarté suffit à elle seule à pousser à écrire une documentation utile
Mais, comme pour tout système, si on s’y accroche trop strictement, cela devient un piège
Ou alors je me demande s’il existe un paradigme unifié
Dans notre organisation, nous utilisons cette méthode, et depuis son adoption notre documentation technique est passée à un tout autre niveau
Avec en plus la propriété des pages et des revues périodiques par chaque propriétaire de page, c’est devenu le seul effort de documentation technique réussi que j’aie vu
Je trouve que le schéma utilisé par Divio est bien plus intuitif : https://docs.divio.com/documentation-system/
Cela dit, Diátaxis semble documenter chaque signification de façon plus exhaustive.
La version remaniée de Divio sur Diataxis.fr a des graphiques moins brouillons, mais elle me paraît essentiellement identique à celle utilisée par Divio.
J’ai toujours considéré les deux ressources comme étant, pour ce qui est des idées qu’elles présentent dans le contexte de leurs sites respectifs, pratiquement le même document.
J’aimerais comprendre en quoi elle est plus intuitive.
J’aime cette idée, et j’ai eu la chance de rencontrer plusieurs fois son créateur à PyConUK. C’est quelqu’un de talentueux et de très gentil.
En revanche, je suis réservé sur le fait de séparer aussi strictement les différents domaines de la documentation.
Lors d’un sprint, on m’a déjà dit que la documentation que je préparais n’était pas acceptable parce qu’elle mélangeait plusieurs formats. Pour préciser, ce n’est pas Daniele qui l’a dit.
Sans vouloir faire argument d’autorité, j’ai été enseignant pendant plus de 20 ans, et j’ai une certaine intuition sur la manière d’expliquer et d’étayer l’apprentissage pour permettre aux gens d’accomplir une tâche tout en construisant leur compréhension.
Tant qu’on évite la rigidité totale, c’est un excellent outil pour réfléchir à la manière de produire de la documentation et à ce que chaque type de document doit accomplir.
Dans des exemples de documentation, par exemple chez numpy, je vois souvent des cas où l’on pourrait faire de bien meilleurs choix que des exemples du type « magie tombée du ciel ».
Un seul exemple bien choisi peut montrer l’usage tout en apportant beaucoup d’apprentissage sur les cas limites ou les points d’attention.
En théorie, je pense que c’est juste, mais j’ai du mal à être d’accord. Les mots sont trop proches.
Pour moi, « tutoriel », « guide pratique » et « explication » ressemblent presque à des synonymes dans les faits.
Quand j’y réfléchis, je comprends qu’il y a de bonnes raisons pour chaque catégorie, mais elles sont sémantiquement trop proches pour que mon cerveau voie la différence.
Quand je veux savoir comment fonctionne quelque chose et que je vois « tutoriel » et « guide pratique », je ne sais pas sur quoi cliquer et je clique simplement sur le premier.
Chercher des termes qui te parlent davantage peut être un exercice utile.
On peut aussi comprendre cela comme une distinction entre action/cognition, c’est-à-dire « faire vs réfléchir », et acquisition/application, c’est-à-dire « en apprentissage vs au travail ».
Il existe aussi une page dédiée à la distinction entre tutoriels et guides pratiques : https://diataxis.fr/tutorials-how-to/
L’une des distinctions les plus simples est que le tutoriel est ce qu’on ne peut pas faire sur Stack Overflow.
Un tutoriel suit un plan de cours défini par l’enseignant et comble les lacunes dont l’étudiant ignore même l’existence.
Sur Stack Overflow, il faut poser une question ; un tutoriel, lui, s’adresse à quelqu’un qui ne sait pas encore quoi demander.
Il existe beaucoup de questions populaires sur la manière d’effectuer une tâche simple, mais pour entrer dans ce format, il faut poser une question plutôt que demander de l’aide de façon vague : https://meta.stackoverflow.com/questions/284236
La documentation Diátaxis explique assez efficacement la différence : un tutoriel est une expérience orientée apprentissage, un guide pratique donne des instructions orientées objectif, une référence est une description technique orientée information, et une explication est une discussion orientée compréhension.
Dans ce système, il faut lire « tutoriel » comme un terme technique, pas comme un mot du langage courant.
C’est un peu comme le mot « depression » employé par un psychologue, qui ne correspond pas exactement à son sens ordinaire.
Cela reste tout de même mieux que de les appeler tutoriels de type I à IV.
Un cours est une explication, un tutoriel ou un TP est une expérience guidée, et cela me fait penser à Contoso, la fausse entreprise de Microsoft.
Un guide pratique, c’est ce dont on a besoin quand on cherche une solution ou qu’on demande à ChatGPT ; une référence, c’est comme un dictionnaire de synonymes, une encyclopédie ou un manuel d’utilisation.
Les jeux vidéo ont des tutoriels intégrés, mais pour les énigmes difficiles, il faut quand même une soluce, et la configuration des touches se vérifie dans la référence.