Imaginez une bibliothèque où tous les livres seraient rangés au hasard : romans, dictionnaires, manuels techniques et guides pratiques mélangés sur les mêmes étagères. Trouver ce qu'on cherche relèverait du défi. C'est exactement le problème que Diataxis résout pour la documentation technique.
Diataxis (du grec ancien dia, « à travers » et taxis, « arrangement ») est un framework qui organise la documentation technique en quatre catégories distinctes, chacune répondant à un besoin d'information différent.
Les 4 types de documentation
Diataxis, créé par Daniele Procida, repose sur deux questions pour classifier n'importe quel contenu de documentation :
- Le lecteur fait-il ou comprend-il quelque chose ? (action ou cognition)
- Est-il en train d'apprendre ou de travailler ? (acquisition ou application)
| Apprendre | Travailler | |
|---|---|---|
| Faire | Tutorial | How-to guide |
| Comprendre | Explanation | Reference |
- Tutorials : apprentissage par l'action. L'auteur prend en charge la totalité du parcours : l'apprenant suit, fait, et acquiert des compétences. L'onboarding d'un nouveau développeur est un tutoriel.
- How-to guides : procédures orientées vers un objectif précis. Le lecteur sait ce qu'il veut faire, il cherche comment. Guide de déploiement, procédure de release, configuration d'un outil.
- Explanation : compréhension des trade-offs et du contexte. Architecture Decision Records, choix techniques, historique des décisions. La seule catégorie que l'on peut lire loin du clavier. Elle répond au « pourquoi ».
- Reference : information factuelle à consulter. API, variables d'environnement, table des rôles. Des faits austères, structurés pour être trouvés rapidement.
Pourquoi séparer ces catégories ?
La séparation n'est pas une question d'organisation esthétique. Elle est fonctionnelle.
Un guide qui mélange la procédure de déploiement et les décisions d'architecture sert mal les deux besoins.
Chaque catégorie répond à un besoin différent. Les mélanger oblige le lecteur à chercher dans du bruit ce qu'il aurait trouvé en deux secondes dans un document ciblé.
Diataxis donne un nom à chaque besoin. En nommant les quatre types, il rend visibles les mélanges qui rendent la documentation difficile à utiliser.
Diataxis en pratique
Le framework s'applique aussi bien à un projet open source qu'à un produit interne. Il peut se traduire par une arborescence de dossiers, un wiki, ou tout autre système de documentation. L'essentiel est que chaque catégorie soit clairement délimitée.
Cette approche est notamment illustrée dans l'anatomie d'un side project drôle fait sérieusement, où Diataxis figure parmi les standards professionnels qui structurent le projet de bout en bout.
Conclusion
Diataxis ne prescrit pas quoi écrire. Il prescrit comment organiser ce qu'on écrit. Simple à comprendre, applicable immédiatement, il réduit le temps que les lecteurs passent à chercher ce qu'ils auraient trouvé en deux secondes dans une documentation bien structurée. Le framework complet est documenté sur diataxis.fr.
