Documentation Symfony : structurer un projet avec l'approche Diataxis

Pourquoi la documentation technique échoue

La plupart des projets Symfony disposent d'une documentation. Peu disposent d'une documentation utile. Le problème n'est ni le volume ni la volonté : c'est l'absence de structure intentionnelle. Un fichier README mêle instructions d'installation, justifications d'architecture et référence API dans un flux continu que personne ne lit en entier.

Diataxis, créé par Daniele Procida, propose un cadre pour résoudre ce problème. Son principe fondateur : la documentation technique répond à quatre besoins cognitifs distincts, et mélanger ces besoins dans un même document dégrade l'ensemble.

Les quatre quadrants de Diataxis

Diataxis repose sur deux axes. Le premier oppose l'apprentissage (acquérir) à l'application (utiliser). Le second oppose la théorie (comprendre) à la pratique (faire). Leur croisement produit quatre types de documentation :

• Tutoriels : apprentissage orienté pratique. Le lecteur ne connaît pas encore le sujet.
• Guides pratiques : résolution de problèmes concrets. Le lecteur sait ce qu'il veut accomplir.
• Référence : description technique exhaustive. Le lecteur cherche une information précise.
• Explications : compréhension approfondie. Le lecteur veut saisir le pourquoi.

Chaque quadrant a ses propres règles de rédaction, son propre ton et sa propre structure. Un tutoriel qui s'interrompt pour expliquer un pattern d'architecture perd son lecteur. Une référence API qui raconte une histoire perd sa fonction de consultation rapide.

Appliquer Diataxis à un projet Symfony

Tutoriels : le parcours d'onboarding

Sur un projet Symfony, le tutoriel correspond au parcours d'onboarding d'un nouveau développeur. Il ne s'agit pas de documenter chaque bundle : il s'agit de guider quelqu'un de git clone jusqu'à sa première contribution fonctionnelle.

Un tutoriel Symfony efficace suit une progression concrète : installer le projet, lancer les conteneurs Docker, créer une entité, écrire un test fonctionnel, observer le résultat. Chaque étape produit un résultat visible. Le développeur qui termine le tutoriel comprend la structure du projet, les conventions de l'équipe et le workflow de développement.

Le piège classique : transformer le tutoriel en encyclopédie. Si votre tutoriel d'onboarding dépasse trente minutes, il contient probablement des explications ou de la référence qui appartiennent à d'autres quadrants.

Guides pratiques : répondre aux problèmes récurrents

Les guides pratiques constituent la section la plus consultée de toute documentation de projet. Sur un projet Symfony, ils répondent aux questions récurrentes : comment ajouter un voter personnalisé, comment configurer un nouveau environnement, comment déboguer un problème de sérialisation avec API Platform.

Un guide pratique commence par le problème, pas par le contexte. Il décrit une séquence d'actions et s'arrête quand le problème est résolu. Il ne justifie pas les choix d'architecture, ne détaille pas les alternatives, ne raconte pas l'historique de la décision. Ces éléments relèvent des explications.

La distinction entre tutoriel et guide pratique est souvent floue dans les projets Symfony. Le critère de démarcation : le tutoriel suppose que le lecteur ne sait pas encore faire, le guide suppose qu'il sait déjà travailler sur le projet mais bute sur un problème spécifique.

Référence : la cartographie technique du projet

La référence technique d'un projet Symfony couvre les contrats d'interface, les configurations disponibles, les événements dispatchés, les services exposés. Elle reflète la structure du code, pas la structure narrative d'un récit.

Sur Symfony, une partie de cette référence peut être générée automatiquement. PHPDoc, OpenAPI pour les endpoints REST, les fichiers de configuration YAML avec leurs options documentées : ces artefacts constituent déjà de la documentation de référence. L'enjeu est de les maintenir synchronisés avec le code, pas de les rédiger manuellement.

La règle cardinale de la référence : elle doit être exacte. Une référence inexacte est pire qu'une absence de référence, car elle induit activement en erreur. L'intégration de la génération de référence dans la CI (vérification de la couverture PHPDoc, validation des schémas OpenAPI) garantit cette exactitude dans la durée.

Explications : les décisions d'architecture

Les explications sont le quadrant le plus négligé et pourtant le plus précieux pour les développeurs seniors. Elles répondent à la question "pourquoi" : pourquoi le projet utilise Messenger plutôt qu'un système de queue maison, pourquoi l'authentification passe par un custom authenticator plutôt que par le guard par défaut, pourquoi le découpage en bounded contexts suit tel périmètre.

Ce quadrant accueille les ADR (Architecture Decision Records), les analyses de compromis, les retours d'expérience post-incident. Il documente le raisonnement derrière le code, information qui disparaît dès que les développeurs originaux quittent le projet.

Outillage et intégration dans le workflow

Diataxis n'impose aucun outil. Cependant, certaines pratiques d'intégration renforcent son efficacité sur un projet Symfony.

Stocker la documentation dans le même dépôt que le code (approche docs-as-code) permet de lier les modifications de documentation aux pull requests qui modifient le comportement. Un template de PR qui inclut une section "documentation impactée" rend le réflexe systématique.

Les générateurs de sites statiques comme Docusaurus ou MkDocs structurent naturellement la navigation en sections qui correspondent aux quadrants Diataxis. Un répertoire docs/tutorials/, docs/how-to/, docs/reference/, docs/explanation/ rend la taxonomie explicite pour les contributeurs.

L'intégration dans la CI va au-delà de la vérification orthographique. Vérifier que les exemples de code compilent, que les liens internes ne sont pas cassés, que la référence générée est à jour : ces contrôles automatisés réduisent la dette documentaire avant qu'elle ne s'accumule.

La documentation comme artefact d'architecture

Pour un architecte, la documentation n'est pas un livrable annexe : c'est un artefact d'architecture au même titre qu'un diagramme C4 ou un schéma de base de données. La qualité de la documentation révèle la qualité de la conception. Un système bien conçu se documente facilement. Un système dont la documentation est confuse trahit une architecture confuse.

Diataxis offre un outil de diagnostic inattendu : si vous ne parvenez pas à rédiger un tutoriel linéaire pour un module, c'est probablement que ce module souffre d'un couplage excessif. Si la référence d'une API est difficile à structurer, l'API elle-même manque peut-être de cohérence. La difficulté à documenter est un signal d'alerte sur la conception.

Gouvernance documentaire à l'échelle

Sur un projet impliquant plusieurs équipes, Diataxis fournit un vocabulaire commun pour la gouvernance documentaire. Plutôt que de débattre du contenu d'un document, les équipes peuvent s'accorder sur son quadrant. Ce cadre partagé simplifie les revues de documentation et réduit les désaccords sur le périmètre de chaque page.

Chaque équipe peut détenir la responsabilité de la référence de ses propres services tout en contribuant aux guides pratiques transverses. Les explications architecturales, elles, relèvent naturellement de la responsabilité de l'équipe plateforme ou de l'architecte. Cette répartition des responsabilités évite le problème classique de la documentation orpheline que personne ne maintient.

Mesurer le retour sur investissement

La documentation a un coût : temps de rédaction, temps de maintenance, temps de revue. Mesurer son retour sur investissement reste un exercice difficile mais nécessaire.

Les indicateurs indirects sont les plus fiables : réduction du temps d'onboarding des nouveaux développeurs, diminution des questions récurrentes sur Slack, baisse du nombre d'incidents liés à une mauvaise compréhension d'un composant. Un suivi trimestriel de ces métriques, même informel, justifie l'investissement en documentation et identifie les quadrants déficitaires.

L'approche incrémentale propre à Diataxis facilite cette mesure : chaque amélioration documentaire est une PR traçable, dont l'impact peut être corrélé à l'évolution des indicateurs.

Pour aller plus loin

• Quel outil choisir pour votre documentation technique ? — Comparer Docusaurus, MkDocs, GitBook et d'autres outils de documentation
• Pourquoi choisir Symfony pour vos projets — Découvrir les atouts du framework Symfony
• Diataxis — Le site officiel du framework Diataxis pour la documentation technique
• Symfony Documentation — La documentation officielle de Symfony, un exemple concret d'application de Diataxis
• Docusaurus — Générateur de sites de documentation open source par Meta
• Write the Docs — Communauté et ressources pour les rédacteurs de documentation technique