On continue cette série d'article avec cette présentation rapide de Diataxis.
Sommaire :
- DiataQuoi ?
- Quel est le concept derrière Diataxis ?
- La Matrice Diataxis (et son compas)
- Comment démarrer ?
- Conclusion
- Sources et references
DiataQuoi ?
DIATAXIS (grec ancien : διάταξις, diataxis, « ordre »)
Diátaxis, écrite par Daniele Procida, est une méthode pour rédiger et organiser la documentation basée sur une compréhension des besoins des utilisateurs.
vous allez voir, c'est très simple à comprendre.
Le but de cet article est de vous faire découvrir Diataxis et de vous fournir des pistes et moyens de tester et de l'implémenter dans vos projets.
Quel est le concept derrière Diataxis ?
Diataxis est basée sur le principe que la documentation DOIT servir aux besoins de son lecteur
moi je l'ai toujours dit hein ...
Daniele pense qu'il n'existe pas un type de documentation, mais 4 types de documentations, avec chacune un lecteur cible et un but différent.
Ce qui implique un contenu et une rédaction spécifique et adaptée.
Si la documentation est faite pour le lecteur, c'est parce qu'elle sert à développer ses connaissances et ses compétences :
La documentation est la première méthode de formation des utilisateurs.
Daniele introduit 2 axes d'analyse des formes de documentation :
- Est-ce qu'on cherche à faire (actions) ou obtenir des connaissances ?
- Est-ce qu'on veut apprend ou appliquer ses compétences ?
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 forme porte des exigences et des directives pour les atteindre.
Pourquoi ?
Introduisons un Concept ;)
| 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 |
| Référence | description, information | "Qu'est-ce que…?" | Décrire les mécanismes | Description brute |
| Concept | Explique, clarifie | "Pourquoi…?" | Eclairer un sujet | Explication didactique |
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 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
Comment démarrer ?
Tout simple lire le site de Diataxis (EN).
14 pages simples, bien chapitrées et organisées, très agréables à lire.
Elles sont répartie en 2 chapitres :
C'est en anglais
Oui, Daniele applique sa méthode sur son site du coup, la meilleure formation reste de le parcourir :)
Lisez et appliquez
Daniele l'écrit sur son site :
"Il n'est pas nécessaire de tout apprendre pour commencer à appliquer".
Vous pouvez déjà commencer à utiliser les guides de rédaction de chaque forme de documentation selon ce que vous voulez faire.
Pour chaque forme de documentation, vous retrouverez :
- le but
- les pièges à éviter
- des principes à appliquer dans votre rédaction
- le langage à employer
Conclusion
La force de Diataxis
Elle n'impose rien, c'est une (bonne) méthode de rédaction avec des check-lists d'éléments à penser pour chaque doc.
C'est simple de s'y référer et de trouver les informations.
On fera des erreurs au début, mais ça aide à améliorer ce que l'on écrit.
ça s'améliorera au fur et à mesure que notre maturité à l'utiliser.
Ce que j'adore dans Diataxis
La qualité du site fait que l'auto-apprentissage est très aisé.
Quand je disais que la doc était le 1er moyen pour se former
Chaque page éclaire simplement une ou plusieurs problématiques que l'on rencontre.
On retrouve dans le contenu les questions qu'on se pose (et on prend un cours de pédagogie en passant) et les erreurs à éviter.
Ça permet de se projeter facilement sur notre documentation, son état des lieux et son avenir.
Et ça peut donner quoi comme résultats ?
Voici plusieurs exemples de documentation réelle avec des Use Case intéressants :
- Openstack https://docs.openstack.org/charm-guide/latest/
- Ubuntu https://ubuntu.com/core/docs
- Cloudflare https://developers.cloudflare.com
- PostgREST https://postgrest.org/en/v12/
- Documentation (très) complexe avec NumPy https://numpy.org/devdocs/dev/index.html
Ressource intéressante :
Article de Rework de la documentation des workers Cloudflare
https://blog.cloudflare.com/new-and-improved-workers-docs/
Sources et Références
3 Talks (Vidéos youtube) de Daniele Procida
Top comments (0)