Mieux écrire, mieux trouver : Diátaxis comme guide de documentation — Touraine Tech 2026 (2026-02-13)

🇫🇷 version below / version 🇫🇷 plus loin

This is the slide deck of a talk (15min) presented at the Touraine Tech conference in February 2026 in Tours by Alexis "Horgix" Chotard about Diátaxis as a documentation framework. Pitch in French below.

Ceci est le deck de slides d'un talk (15min) présenté à la conférence Touraine Tech en février 2026 à Tours par Alexis "Horgix" Chotard au sujet de Diátaxis en tant que framework de documentation. Pitch ci-dessous.

💬 Pitch/astract:
Bien documenter, surtout dans des cas tels qu'une plateforme interne, c’est essentiel… mais entre les contributions dispersées, les outils tiers déjà documentés, et les besoins variés des utilisateurs, structurer cette documentation devient vite un casse-tête pour les auteurs de documentation. Sans même parler de se retrouver dans un tel fouillis pour les lecteurs en quête d'une information précise !

C’est précisément ce que cherche à résoudre la méthode Diátaxis (https://diataxis.fr/), en séparant clairement quatre types de documentation (venez découvrir lesquels !) adressant chacun différents besoins utilisateur de la manière la plus appropriée possible.

Ce talk propose une introduction claire et actionnable à Diátaxis :

- les fondements de la méthode et sa logique de séparation des besoins
- pourquoi cette structure aide à mieux écrire, mieux maintenir, et mieux naviguer
- des conseils pour adopter Diátaxis de façon incrémentale
- un bref retour d’expérience d’une migration réussie sur plusieurs corpus de documentation interne (chez PayFit)

Transcript

1. 1 28 juin 2024 Alexis “@Horgix” Chotard Alerte, tout brûle ! Comment gérer des incidents techniques Mieux écrire, mieux trouver : Diátaxis comme guide de documentation 13 fev. 2026 Alexis “Horgix” Chotard
2. 2 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr SRE / Staff Engineer ❤ Automatisation ❤ Rust ❤ Cloud Native ❤ Open Source @Horgix.fr Horgix Alexis “Horgix” Chotard Horgix
3. 3 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr Diátaxis en bref – https://diataxis.fr/ Créé par Daniele Procida (󰏅 / 󰐗) 😌 Approche systématique 🧩 Centré sur les besoins 🧭 Exemples: 🧪 2014–2021 @ Divio de la conception de documentation technique des utilisateurs de la documentation Django, Snowpack, Cloudflare Workers, Numpy, …
4. 4 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr La “map” de documentation selon Diátaxis
5. 5 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr La “map” de documentation selon Diátaxis
6. 6 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr La “map” de documentation selon Diátaxis
7. 7 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr La “map” de documentation selon Diátaxis
8. 8 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr La “map” de documentation selon Diátaxis
9. 9 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr La “map” de documentation selon Diátaxis
10. 10 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr La “map” de documentation selon Diátaxis
11. 11 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr À quoi ça correspond tout ça ?
12. 12 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr À quoi ça correspond tout ça ? Tutoriels Ce qu’ils font Introduisent, forment, accompagnent Répond à la question « Peux-tu m’apprendre à… ? » Orienté vers L’apprentissage Forme Cours Analogie Apprendre à un enfant à cuisiner Note Pas d’enseignant “à côté”
13. 13 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr À quoi ça correspond tout ça ? Tutoriels Guides pratiques Ce qu’ils font Introduisent, forment, accompagnent Orientent, montrent le chemin Répond à la question « Peux-tu m’apprendre à… ? » « Comment est-ce que je… ? » Orienté vers L’apprentissage Des objectifs Forme Cours Série d’étapes Analogie Apprendre à un enfant à cuisiner Une recette dans un livre de cuisine Note Pas d’enseignant “à côté” Utilisateur déjà compétent
14. 14 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr À quoi ça correspond tout ça ? Tutoriels Guides pratiques Références Ce qu’ils font Introduisent, forment, accompagnent Orientent, montrent le chemin Énoncent, décrivent, informent Répond à la question « Peux-tu m’apprendre à… ? » « Comment est-ce que je… ? » « Qu’est-ce que… ? » Orienté vers L’apprentissage Des objectifs L’information Forme Cours Série d’étapes Description factuelle Analogie Apprendre à un enfant à cuisiner Une recette dans un livre de cuisine Les infos au dos d’un paquet alimentaire Note Pas d’enseignant “à côté” Utilisateur déjà compétent Neutre
15. 15 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr À quoi ça correspond tout ça ? Tutoriels Guides pratiques Références Explications Ce qu’ils font Introduisent, forment, accompagnent Orientent, montrent le chemin Énoncent, décrivent, informent expliquent, clarifient, discutent Répond à la question « Peux-tu m’apprendre à… ? » « Comment est-ce que je… ? » « Qu’est-ce que… ? » « Pourquoi… ? » Orienté vers L’apprentissage Des objectifs L’information Lla compréhension Forme Cours Série d’étapes Description factuelle Explication discursive Analogie Apprendre à un enfant à cuisiner Une recette dans un livre de cuisine Les infos au dos d’un paquet alimentaire Un article sur l’histoire sociale de la cuisine Note Pas d’enseignant “à côté” Utilisateur déjà compétent Neutre “Concepts”, contexte
16. 16 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr Exemple : critères pour un bon tutoriel ➔ Significatif – l'élève doit ressentir un sentiment d'accomplissement ➔ Réalisable avec succès – l'élève doit être capable de le mener à bien ➔ Logique – le parcours suivi par l'élève doit avoir du sens ➔ Utilisable de manière complète – l'élève doit rencontrer toutes les actions, concepts et outils avec lesquels il doit se familiariser
17. 17 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr Exemple : critères pour un bon tutoriel ➔ Significatif – l'élève doit ressentir un sentiment d'accomplissement ➔ Réalisable avec succès – l'élève doit être capable de le mener à bien ➔ Logique – le parcours suivi par l'élève doit avoir du sens ➔ Utilisable de manière complète – l'élève doit rencontrer toutes les actions, concepts et outils avec lesquels il doit se familiariser
18. 18 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr Exemple : critères pour un bon tutoriel ➔ Significatif – l'élève doit ressentir un sentiment d'accomplissement ➔ Réalisable avec succès – l'élève doit être capable de le mener à bien ➔ Logique – le parcours suivi par l'élève doit avoir du sens ➔ Utilisable de manière complète – l'élève doit rencontrer toutes les actions, concepts et outils avec lesquels il doit se familiariser
19. 19 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr Exemple : critères pour un bon tutoriel ➔ Significatif – l'élève doit ressentir un sentiment d'accomplissement ➔ Réalisable avec succès – l'élève doit être capable de le mener à bien ➔ Logique – le parcours suivi par l'élève doit avoir du sens ➔ Utilisable de manière complète – l'élève doit rencontrer toutes les actions, concepts et outils avec lesquels il doit se familiariser Problème pédagogique Fournir des résultats tôt et souvent Avoir un narratif 󰠈 ♻ 📚 Considération pour les erreurs rencontrées ⚠
20. 20 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr La “map” de documentation selon Diátaxis
21. 21 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr Exemples @ PayFit (observabilité, plateforme) Tutorial Troubleshooter une application instrumentée en production How-to Comment estimer le coût de ses métriques custom Datadog en fonction de leur cardinalité Explanation / Concept Datadog APM Resource Quantization Reference Convention de nommage des métriques custom, durée de rétention, … Acquisition Application Action Réflexion
22. 22 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr En quoi ça nous aide tout ça ? • Clarifier nos propres intentions • Adapter les formulations, le niveau de détail • Plus facile à review et garder à jour • Trouver ce qu’on cherche plus efficacement en fonction de notre situation / intention / besoin • N’adresser que ce que l’on cherche, sans superflu Écriture de documentation Consultation de documentation
23. 23 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr 23 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr 2 tips Pour quand vous tenterez Diátaxis en sortant de ce talk (n’est-ce pas ?)
24. 24 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr Soyez spécifiques – Évitez la confusion
25. 25 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr Soyez spécifiques – Évitez la confusion Monitoring ⚠
26. 26 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr Soyez spécifiques – Évitez la confusion Monitoring ⚠ Monitoring de performance et TypeScript ❌
27. 27 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr Soyez spécifiques – Évitez la confusion Monitoring ⚠ Monitoring de performance et TypeScript ❌ How-to: intégrer le monitoring de performance avec Datadog à votre application TypeScript ✅
28. 28 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs
29. 29 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
30. 30 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
31. 31 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
32. 32 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
33. 33 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
34. 34 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
35. 35 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
36. 36 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
37. 37 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
38. 38 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
39. 39 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
40. 40 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr N’ayez pas peur de découper et croiser les refs Tutorials How-to Explanations References Acquisition Application Action Réflexion
41. 41 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr 41 2026-02-13 Diátaxis comme guide de documentation Alexis “Horgix” Chotard @Horgix.fr « La meilleure façon de se lancer avec Diátaxis, c’est de l’appliquer — à quelque chose, même de très modeste. » https://diataxis.fr/start-here/
42. 42 28 juin 2024 Alexis “@Horgix” Chotard Alerte, tout brûle ! Comment gérer des incidents techniques Mieux écrire, mieux trouver : Diátaxis comme guide de documentation 13 fev. 2026 Alexis “Horgix” Chotard Q&A Merci ! Slides ↓ https://bsky.app/profile/Horgix.fr Votre feedback compte <REDACTED> Il fallait être là pendant la conférence :)