Diátaxis appliqué à la doc de plateforme — BreizhCamp 2025 (2025-06-26)

🇫🇷 version below / version 🇫🇷 plus loin

This is the slide deck of a talk (25min) presented at the BreizhCamp conference in June 2025 in Rennes by Alexis "Horgix" Chotard about Diátaxis and platform documentation. Pitch in French below.

Ceci est le deck de slides d'un talk (25min) présenté à la conférence BreizhCamp en juin 2025 à Rennes par Alexis "Horgix" Chotard au sujet de Diátaxis appliqué à la documentation de plateform. Pitch ci-dessous.

💬 Pitch/astract:
Bien documenter 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. Heureusement, Diátaxis (https://diataxis.fr/) est venu à notre rescousse !

Chez PayFit, nous avons décidé de refondre entièrement la documentation de notre plateforme interne en adoptant cette méthodologie, avec un parti pris : organiser chaque section (Tutoriels, How-To, Explications, Reference) autour des cas d’usage de la plateforme pour une approche 100% developer-centric.

Le résultat ? De nombreuses identifications de doublons de documentation (!), une contribution plus fluide, une identification plus aisée des éléments manquants, et une meilleure navigation pour les utilisateurs de notre plateforme interne.

De la méthode Diátaxis en elle-même à la solution de rendu (du bon vieux mkdocs ? Un developer portal ? Un site dédié basé sur Astro/Starfish ?), en passant par quelque tips pour rendre la contribution à la doc moins rébarbative, ce talk vous donnera des clés actionnables pour rentre votre documentation plus utile et efficace !

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 appliqué à la doc de plateforme 26 juin 2025 Alexis “Horgix” Chotard
2. 2 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr SRE / Staff Engineer ❤ Automatisation ❤ Rust ❤ Cloud Native ❤ Open Source @Horgix.fr Horgix Alexis “Horgix” Chotard Horgix
3. 3 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr 3 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Diátaxis La théorie
4. 4 2025-06-24 Diátaxis appliqué à la doc de plateforme 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, …
5. 5 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr La “map” de documentation selon Diátaxis
6. 6 2025-06-24 Diátaxis appliqué à la doc de plateforme 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 une leçon Analogie apprendre à un enfant à cuisiner Note Pas d’enseignant “à côté”
7. 7 2025-06-24 Diátaxis appliqué à la doc de plateforme 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 une leçon une 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
8. 8 2025-06-24 Diátaxis appliqué à la doc de plateforme 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 une leçon une série d’étapes une 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
9. 9 2025-06-24 Diátaxis appliqué à la doc de plateforme 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 la compréhension Forme un cours une série d’étapes une description factuelle une 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
10. 10 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr La “map” de documentation selon Diátaxis
11. 11 2025-06-24 Diátaxis appliqué à la doc de plateforme 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
12. 12 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Exemples @ PayFit (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 Datadog APM Resource Quantization Reference / Concept Convention de nommage des métriques custom, durée de rétention, … Acquisition Application Action Réflexion
13. 13 2025-06-24 Diátaxis appliqué à la doc de plateforme 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
14. 14 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr 14 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr « N'attendez pas de comprendre Diátaxis avant de commencer à essayer de le mettre en pratique » Du coup… parlons concrêt ! – https://diataxis.fr/application/
15. 15 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr 15 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr La doc chez PayFit Une longue histoire avec des aller-retours
16. 16 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr La doc chez PayFit – ~2020 Chacun render son truc dans son coin Multiples URLs à découvrir ↔ Impossible de rechercher partout 🔗 🔍 Faible valeur ajoutée 🤷
17. 17 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr ~2021 @ PayFit – Hello Backstage ! Plus un framework 🏗 qu’un outil clés en main Merci https://github.com/cncf/artwork/ ❤ Developer portal 󰳕 - Service catalog - Scaffolding - Rendering mkdocs !
18. 18 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Backstage techdocs – Enrôlement 1⃣ Écrire sa doc en markdown dans son repo git 2⃣ Un petit bout dans le pipeline de CI 3⃣ Profit !
19. 19 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Backstage – Catalog
20. 20 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Backstage – Component
21. 21 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Backstage techdocs – Résultat
22. 22 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Backstage techdocs : finalement “meh” ➔ Recherche par défaut “nulle” (pas autant que Notion !) → Algolia home-made ➔ Rendering visuel pas super plaisant ➔ Chargement des pages pas super fluide (mais OK) ➔ Pendant ce temps : ➔ ➡ De nouveau certaines équipent qui render leur propre doc
23. 23 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr 2024 – Nouvelle doc front-end “à part”
24. 24 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr “Why creating a doc instead of using the dev portal?”
25. 25 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Derrière le rideau: https://(starlight.)astro.build/
26. 26 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr La doc de notre écosystème front-end
27. 27 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr La doc de notre plateforme d’événements
28. 28 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr 28 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Diátaxis à la rescousse de la documentation de notre internal developer platform
29. 29 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr ADR
30. 30 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr ADR – La suite
31. 31 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Ça vous parle le cycle logiciel “classique” ?
32. 32 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Documentation orientée “use case”
33. 33 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Les sections actuelles ➔ Develop locally ➔ Document technical things ➔ Build artefacts ➔ Deploy artefacts ➔ Deploy infrastructure ➔ Ensure reliability ➔ Expose workloads ➔ Audit workloads ➔ Observe workloads ➔ Troubleshoot workloads Disclaimer : Encore beaucoup de clarté à apporter, et une “vigilance” permanente pour garder quelque chose de clair
34. 34 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr La “migration” Vrai travail de “repenser” et refacto ✂ Attention particulière à l’expérience des lecteurs 📋 la doc selon Diátaxis Redirections, disclaimers, etc.
35. 35 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Exemple de PR
36. 36 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Le résultat ? Plus grande clarté lors des nouvelles contributions 😌 🧹 Plus facile de trouver ce qu’on cherche 󰡸 Identification plus aisée des “trous” 🎾 Nettoyage ! Moins Plus de duplicatas ! Plus de screenshots de doc upstream
37. 37 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Backstage – Catalog
38. 38 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr 38 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Tips Sur cette expérience. Vous êtes prêts ? On va speedrun !
39. 39 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Tips ➔ Ne pas hésiter à rediriger vers autre chose (doc spécifique, autre section) ➔ Créez les pages manquantes avec “TODO” en contenu ➔ Reposez vous sur de la CI : liens morts, syntaxe markdown, … spellcheck ➔ Des noms de fichiers adaptés… ➔ Git LFS, et dossier images/ “vrac” ou par section ➔ Ajoutez des guidelines de contribution
40. 40 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Soyez spécifiques ➔ … quand nécessaire; évitez la confusion (e.g. Datadog Custom Metrics) ◆ Good: How to integrate application performance monitoring ◆ Bad: Integrating application performance monitoring ◆ Very bad: Application performance monitoring ➔ “In this tutorial we will create and deploy a scalable web application. Along the way we will encounter containerisation tools and services.” ◆ VS In this tutorial you will learn…
41. 41 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr 41 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Pour aller plus loin Ce qu’on pourrait faire mieux
42. 42 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr Le retour des problèmes similaires distribués
43. 43 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr “Why creating a doc instead of using the dev portal?”
44. 44 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr La route est encore longue Astro + Starfish dans le DevPortal ? 🌟 “Tech writing” pour de vrai ✒ Mesurer 📊 TODO ⏩ Blocks dynamiques, meilleure recherche, look’n’feel – dans Backstage Google Developers → Tech Writing Courses for Engineers - Pages accédées - Noter / Voter - Résultats de recherche Encore beaucoup de contenu à écrire, refacto permanent, etc. :)
45. 45 2025-06-24 Diátaxis appliqué à la doc de plateforme Alexis “Horgix” Chotard @Horgix.fr 45 2025-06-24 Diátaxis appliqué à la doc de plateforme 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/
46. 46 28 juin 2024 Alexis “@Horgix” Chotard Alerte, tout brûle ! Comment gérer des incidents techniques Mieux écrire, mieux trouver : Diátaxis appliqué à la doc de plateforme 26 juin 2025 Alexis “Horgix” Chotard Q&A Votre feedback compte Slides → https://bsky.app/profile/Horgix.fr Merci !