Enseignements du framework Diátaxis
Conçu par un spécialiste de documentation technique, le cadre de travail Diátaxis permet d’améliorer la qualité de ses pages web dans d’autres domaines que le code logiciel.
Diátaxis en bref
Le framework Diátaxis propose des principes pour une approche systématique de la rédaction de documentation technique. Je pense qu’il peut être utilisé pour toute forme de documentation. Il a été développé par Daniele Procida.
Par la structure qu’il propose, il facilite l’utilisation de la documentation pour les internautes et les maintenance pour les rédacteurs et rédactrices.
Les 4 types de contenus de toute documentation sont regroupés en en 2 axes:
- les tutoriels sont orientés vers l’apprentissage et sont utiles à l’action
- les guides how-to sont sont orientés vers l’application et sont utiles à l’action
- les références sont orientés vers l’application et sont utiles à l’action à la connaissance
- les explications sont orientés vers l’apprentissage et son utiles à la connaissance
En plus du site de référence, je conseille les vidéos suivantes pour en apprendre plus:
- découverte de l’outil: What nobody tells you about documentation
- atelier: Python Docs Community Workshop: Introduction to Diataxis
- sur la croissance d’un corpus: Always complete, never finished
Voici ce qui m’a intéressé (et convaincu) dans la démarche.
Regrouper par catégories
Le classement des contenus en 4 catégories permet de hiérarchiser l’information et de rapprocher ce qui doit l’être. Une structure propre est une condition nécessaire pour naviguer efficacement dans une documentation d’une certaine taille.
Le moteur de recherche ou l’index alphabétique ne remplaceront jamais une bonne structure. La chronologie d’un blog ou les liens très nombreux d’un wiki ne permettent pas non plus d’aider les internautes à comprendre comment est structurée la documentation.
Sur ce thème, je conseille aussi la conférence Building navigation for your doc site: 5 best practices par Tom Johnson. Elle est complémentaire au travail de Daniele Procida.
En passant, je fais remarquer qu’une taxonomie est presque toujours pensée comme un arbre. Mais elle devrait d’abord être pensée comme un moyen de regroupement. C’est ensuite seulement qu’elle peut prendre la forme d’un arbre (ou pas). Le groupement par proximité est premier.
À terme, dans un corpus qui grandit, si les regroupements ne sont pas clairs, c’est la gabegie assurée.
Publics cibles et personnes différentes
Les 4 catégories de Diátaxis s’adressent à plusieurs publics cibles et à des personnes différentes. Un exemple tout simple:
- le tutoriel de la mousse au chocolat sur YouTube est fait pour les enfants qui n’ont jamais cuisiné (mais qui veulent faire une surprise à leurs parents)
- la recette de la mousse au chocolat est un guide how-to destiné aux personnes qui cuisinent (vous et moi)
- l’explication sur la chimie de la mousse au chocolat est destinée aux personnes curieuses (mais qui ne cuisinent pas forcément)
En première approche, on pourrait dire que chaque public cible peut être intéressé par 1 ou 2 catégories. C’est une manière de voir les choses, mais je pense qu’elle est erronée. Une personne peut être intéressée à 1, 2, 3 ou 4 catégories de contenu.
Temporalité différente pour des mêmes personnes
Il faudrait plutôt dire que chaque personne peut être intéressée par les 4 catégories, mais à des moments différentes. La notion de temporalité est plus intéressants, parce qu’évolutive.
Les enfants qui ont suivi le tutoriel pour leur première mousse au chocolat utiliseront peut-être une recette (sans passer par un tuto) pour leur prochaine création. Et je parie que les ados pourraient bien lire quelque chose sur la cuisine moléculaire.
Pour moi, cette notion de moment est la plus grande force de Diátaxis. Une même personne a besoin de contenus différents en fonction de sa tâche du moment. C’est parce que les besoins varient en fonction du temps que la structure doit être particulièrement propre.
Rigueur et non linéarité
Le plus grand risque avec cet outil, c’est de penser qu’il y a une évolution «linéaire» entre les différentes catégories. D’abord un tuto, puis un how-to, etc. C’est faux!
Les parcours peuvent être multiples. Je vous passe toutes la navigations possibles entre les différents éléments d’une documentation, que ce soit de la cuisine, de la programmation, le pilotage d’une avion ou le vélo (des exemples de Procida).
La structure doit être assez claire pour permettre de sauter sans hésitation d’un type de contenu à l’autre à un moment précis. J’ai besoin de ceci, je sais que je vais trouver la réponse là!
Depuis que j’ai écouté et lu Procida, je vois souvent les choses sous un autre angle. Je combats désormais souvent ma tentation d’introduire des «motifs antipédagigiques» (introduire des éléments d’explication dans un tutoriel, par exemple), sans toujours y parvenir.
Je suis convaincu que derrière le paradoxe de l’utilisation d’un outil technique pour des contenus non techniques se cachent pas mal de pistes pour améliorer l’efficacité des publications sur le web. Je suis intéressé pour tous vos retours sur Diátaxis pour des documentations généralistes.