Cet article fait suite à mon précédent article :
https://dev.to/onepoint/les-peches-capitaux-du-dossier-darchitecture-technique-111p
Dans le monde tech, je trouve qu'un paradoxe persiste :
Nous avons mis en place des outils ultra-modernes, mais la transmission orale du savoir reste dominante.
"Va voir Paul, il connaît bien le sujet" ou "Rajoutes Marie à la réunion, elle maîtrise cette partie-là" sont des phrases qu'on entend quotidiennement.
Pourquoi ce réflexe de l'oral ? La réponse est souvent simple : personne ne fait confiance à la documentation existante. Trop dispersée, mal structurée, obsolète... bref, chaotique.
En travaillant sur les erreurs du DAT, j'en ai tiré la conclusion que le DAT n'est que la partie émergée de l'iceberg : c'est toute notre approche de la documentation qui mérite d'être repensée.
Car au fond, comment créer une documentation en laquelle les équipes auront vraiment confiance ? Comment passer d'une culture de l'oral à une vraie culture de la documentation ?
C'est là qu'intervient une approche qui a révolutionné ma vision : la méthode Diataxis.
Sommaire :
DiataQuoi ?
DIATAXIS (grec ancien : διάταξις, diataxis, « ordre »)
Diataxis, développée par Daniele Procida, propose une méthodologie pour structurer et rédiger la documentation en se fondant sur la compréhension des besoins des utilisateurs.
vous allez voir, c'est très simple à comprendre.
Les principes fondamentaux de Diataxis
Diataxis repose sur le principe que la documentation DOIT répondre aux besoins de son lecteur.
Selon Daniele Procida, il existe quatre catégories de documentation, chacune correspondant à un lecteur cible et un objectif spécifique.
Cette classification implique un contenu et une approche rédactionnelle adaptés à chaque type.
La documentation constitue le principal vecteur de formation des utilisateurs, car elle développe leurs connaissances et leurs compétences.
La méthode s'articule autour de deux axes d'analyse :
- L'objectif : acquisition de compétences pratiques ou de connaissances théoriques
- L'usage : apprentissage ou application
La Matrice Diataxis (et son compas)
| si le contenu décrit des | ... et permet à l'utilisateur d' ... | ... alors c'est une forme de ... |
|---|---|---|
| actions | acquérir des compétences | Tutoriel (tutorial) |
| actions | appliquer ses compétences | Guide (how-to) |
| connaissances | acquérir des compétences | Concept (explanation) |
| connaissances | appliquer ses compétences | Référence (reference) |
(J'ai indiqué aussi les termes anglais pour vous repérer dans la doc de Diataxis en anglais)
On aboutit à cette matrice :
Chaque type de documentation possède ses caractéristiques et directives spécifiques.
Pourquoi ?
Introduisons un Concept "Acquisition-Connaissance" ;)
| Que font-ils ? | Répondent à la question | Objectif | Forme | |
|---|---|---|---|---|
| Tutoriel | introduction, éducation | “Pouvez-vous m’apprendre à … ?” | Fournir un apprentissage | Leçon |
| Guide | guide, procédure | "Comment je fais pour… ?" | Atteindre un but spécifique | Série d'étapes |
| Concept | explique, clarifie | "Pourquoi… ?" | Eclairer un sujet | Explication didactique |
| Référence | description, information | "Qu'est-ce que… ?" | Décrire les mécanismes | Description brute |
Exemples :
"Je voudrais installer ma première application" ⇾ action & acquérir des compétences ⇾ Tutoriel
"Je voudrais comprendre le choix client/serveur" ⇾ connaissance et acquérir des compétences ⇾ Concept
"Je voudrais configurer finement la base de donnée de mon application" ⇾ action et appliquer des compétences ⇾ Guide
"Je cherche le swagger de l'api de l'application" ⇾ connaissance et appliquer des compétences ⇾ Reference
À RETENIR
- Un document = une seule orientation
- Chaque type renvoie vers les autres types complémentaires
- La documentation forme un réseau cohérent de documents interconnectés
Conséquences pratiques :
- Un tutoriel ou guide pratique n'explique pas les concepts sous-jacents
- La description d'un concept technique n'inclut pas les détails d'installation
- La documentation devient une structure cohérente de documents interconnectés
La transformation Diataxis : un exemple concret
AVANT : Documentation classique
📄 "Documentation Application"
- Présentation
- Installation
- Architecture
- Manuel utilisateur
- Guide développeur
- Guide administrateur
- API
- Exploitation
APRÈS : Documentation Diataxis
📚 Documentation structurée
├── 👤 Utilisateur métier
│ ├── 🎓 Tutoriels
│ │ ├── "Premiers pas sur l'application"
│ │ └── "Créer votre premier dossier"
│ ├── 📖 Guides pratiques
│ │ ├── "Gestion des profils"
│ │ ├── "Import de données"
│ │ └── "Tableaux de bord"
│ ├── 💡 Concepts
│ │ ├── "Vue d'ensemble"
│ │ └── "Processus métier"
│ └── 📚 Référence
│ ├── "Guide des écrans"
│ └── "Liste des raccourcis"
│
├── 🛠 Développeur
│ ├── 🎓 Tutoriels
│ │ ├── "Setup environnement"
│ │ └── "Première feature"
│ ├── 📖 Guides pratiques
│ │ ├── "Tests unitaires"
│ │ ├── "Debug local"
│ │ └── "CI/CD"
│ ├── 💡 Concepts
│ │ ├── "Architecture logiciel"
│ │ └── "Design patterns"
│ └── 📚 Référence
│ ├── "API Reference"
│ └── "Code style"
│
└── 🔧 Ops
├── 🎓 Tutoriels
│ ├── "Premier déploiement"
│ └── "Setup monitoring"
├── 📖 Guides pratiques
│ ├── "Scalabilité"
│ ├── "Backup/Restore"
│ └── "Incident management"
├── 💡 Concepts
│ ├── "Infrastructure"
│ └── "Sécurité"
└── 📚 Référence
├── "Configuration"
└── "Métriques"
Mise en œuvre de Diataxis
Une application progressive
Pour débuter, consultez le site Diataxis (en anglais).
La documentation, concise et structurée, comprend 14 pages réparties en deux sections :
Pour chaque forme de documentation, vous retrouverez :
- le but
- les pièges à éviter
- des principes à appliquer dans votre rédaction
- le langage à employer
Checklist de migration
Je vous propose une petite check-list de migration pour débuter, je la développerais plus dans le guide de migration du DAT (qui arrive, qui arrive).
-
Audit de l'existant
- Listez tous vos documents actuels
- Identifiez leur usage principal
-
Catégorisation
- Classez chaque document selon la matrice
- Identifiez les chevauchements
-
Plan d'action
- Définissez les priorités
- Établissez un calendrier
- Commencez petit, itérez souvent
Des pièges à éviter
❌ Ne pas faire
- Mélanger tutoriel et référence technique
- Créer une doc "one size fits all"
- Négliger les liens entre documents
✅ Bonnes pratiques par type
Tutoriels
- Montrer le résultat final attendu
- Découper en étapes de 5-10 minutes
- Inclure des captures d'écran
- Tester sur environnement vierge
Guides
- Un objectif = un guide
- Lister les prérequis
- Proposer des alternatives
- Anticiper les erreurs
Concepts
- Utiliser des analogies
- Inclure des schémas
- Expliquer le "pourquoi"
- Lier aux concepts connexes
Référence
- Structure cohérente
- Exhaustivité
- Exemples pratiques
- Mise à jour régulière
Bénéfices concrets
Appliquer cette méthode est positive autant pour les utilisateur que pour les équipes.
Pour les utilisateurs
- Navigation intuitive
- Apprentissage progressif
- Autonomie accrue
- Satisfaction améliorée
Pour les équipes
- Réduction du temps de formation
- Moins d'interruptions
- Maintenance facilitée
- Meilleure collaboration
Pensez à Mesurer le succès
Si on veut que notre documentation soit efficace et serve enfin, il est préférable de mesurer son usage.
Propositions d'indicateurs clés :
- Temps moyen de recherche d'information
- Taux de consultation
- Retours utilisateurs
Des exemples de réussites
Diataxis reste populaire sans être hype. On trouve facilement beaucoup d'entreprises (US majoritairement) qui l'ont mis en oeuvre pour leurs produits.
Des entreprises de référence utilisent Diataxis :
- OpenStack : docs.openstack.org/charm-guide/latest/
- Ubuntu : ubuntu.com/core/docs
- Cloudflare : developers.cloudflare.com
- PostgREST : postgrest.org/en/v12/
- NumPy : numpy.org/devdocs/dev/index.html
Et voici un REX sur une refonte Diataxis :
Retour d'expérience sur la refonte de la documentation Cloudflare Workers
Conclusion
La force de Diataxis réside dans :
- Sa simplicité conceptuelle
- Sa flexibilité d'application
- Son focus sur les besoins utilisateurs
- Sa capacité à évoluer progressivement
Même une application imparfaite de Diataxis améliore significativement la qualité documentaire. La maîtrise vient avec la pratique.
Sources et Références
- Site officiel : diataxis.fr Présentations de Daniele Procida :
- "What nobody tells you about documentation"
- "Python Docs Community Workshop: Introduction to Diataxis"
- "Always complete, never finished"
Cet article fait partie du "Advent of Tech 2024 Onepoint", une série d'articles tech publiés par Onepoint pour patienter jusqu'à Noël.
Voir tous les articles du Advent of Tech 2024
Top comments (1)
Très bon article !
Tu as aussi la doc de quarkus qui suit ce principe.