Comment produire la documentation sur votre projet Symfony avec l’approche Diátaxis ?

‍

Le but de l'outil Diátaxis est d’apporter un cadre pour structurer la documentation technique, en prenant en compte les besoins des utilisateurs, dans notre cas, les développeurs.

Quatre types de documentation sont mis en avant:

• tutoriels
• guides pratiques
• références techniques
• explications

Chacun de ces types répond à des besoins et des objectifs différents des utilisateurs pour apporter de la qualité dans la documentation.

Il est facilement compréhensible, simple à appliquer et léger, sans imposer de contraintes de mise en œuvre. Diátaxis a déjà été utilisé avec succès dans de nombreux domaines et applications, qu'il s'agisse de projets de documentation de grande ou de petite envergure, qu'ils soient open-source ou propriétaires.

Comment utiliser Diátaxis ?

Diátaxis est basé sur des principes théoriques solides et a fait ses preuves dans la pratique, mais ce n'est pas le dernier mot de la documentation. La seule valeur qu'il peut vous offrir est d'être utile pour aider à rendre votre documentation meilleure pour ses utilisateurs, et plus facile à créer et à maintenir pour vous.

La meilleure chose que vous puissiez en faire est donc d'en tirer quelque chose qui semble fonctionner pour vous : autant ou aussi peu que vous le souhaitez.

Utilisez Diátaxis comme guide, pas comme plan

Le but de Diátaxis est de vous donner un moyen de réfléchir et de comprendre votre documentation, afin que vous puissiez mieux comprendre ce qu'elle fait et ce que vous essayez d'en faire. Il fournit des outils qui aident à l'évaluer, à identifier où se situent ses problèmes et à juger ce que vous pouvez faire pour l'améliorer.

Ne vous souciez pas de la structure

Si vous continuez à suivre les recommandations fournies par Diátaxis, votre documentation finira par adopter la structure Diátaxis - mais elle aura adopté cette forme car elle a été améliorée. Ce n'est pas l'inverse, qu'il faut imposer la structure à la documentation pour l'améliorer.

Travaillez une étape à la fois

Il est naturel de vouloir terminer de grandes tranches de travail avant de les publier, de sorte que vous ayez quelque chose de substantiel à montrer à chaque fois. Évitez cette tentation - chaque pas dans la bonne direction vaut la peine d'être publié immédiatement.

Faites juste quelque chose

Si vous réparez un énorme gâchis, la tentation est de tout détruire et de recommencer. Encore une fois, évitez-le. En ce qui concerne l'amélioration de la documentation en ligne avec Diátaxis, il n'est pas nécessaire de chercher des choses à améliorer. Au lieu de cela, la meilleure façon d'appliquer Diátaxis est la suivante :

• Choisissez quelque chose - n'importe quel élément de la documentation. 
• Évaluez-le . Ensuite, considérez cette chose de manière critique. 
• Décidez quoi faire . Décidez, sur la base de vos réponses à ces questions : 
• Faites-le . Terminez cette action unique suivante et publiez la
• Et puis revenir au début du cycle.

Travailler ainsi aide à réduire le stress de l'un des aspects les plus paralysants et gênants du travail du rédacteur de documentation : savoir quoi faire. Il maintient le travail dans la bonne direction, toujours vers la fin souhaitée, sans avoir à dépenser des énergies sur un plan.

Aspect 1: les Tutoriels

L'objectif est d'aider un débutant à acquérir les compétences de base nécessaires pour utiliser le projet, et le code, afin qu'il puisse l'utiliser de manière autonome. En outre, un didacticiel doit aider l'apprenant à avoir confiance en sa capacité à réussir avec le produit, en lui permettant de réaliser quelque chose de significatif et réalisable. 

En d'autres termes, un didacticiel est une leçon pratique qui vise à apprendre comment faire quelque chose plutôt que simplement apprendre des connaissances théoriques. Une fois le didacticiel terminé, l'apprenant devrait être capable de comprendre le reste de la documentation et d'utiliser le code de manière autonome. 

Il faut amener le tuto comme on amène un enfant à aimer la cuisine. Faire faire des choses simples, qui mettent en confiance et offrir une expérience agréable, qui donnent envie de recommencer sinon vous risquez de perdre votre interlocuteur. Cependant, il est important de ne pas trop insister, car cela peut être inutile et contre-productif. L’interlocuteur apprendra aussi sur le tas, par la répétition, et à faire les choses dans le bon ordre.

Comment le rédiger ?

L'apprentissage commence par la pratique. Un apprenant doit être guidé à travers les étapes simples, en utilisant les outils et les opérations qu'il devra maîtriser. Les didacticiels doivent permettre aux apprenants de voir rapidement les résultats de leurs actions, ce qui aide à maintenir leur motivation et leur confiance. 

Le langage des tutoriels

Dans ce tutoriel, vous allez…

Décrivez ce que l'apprenant accomplira (remarque - et non : "vous apprendrez...").

Tout d'abord, faites x. Maintenant, faites-y. Maintenant que vous avez fait y, faites z.

Pas de place pour l'ambiguïté ou le doute.

Il faut toujours faire x avant de faire y parce que… (voir Explication pour plus de détails).

Fournissez une explication minimale des actions dans le langage le plus élémentaire possible. Lien vers une explication plus détaillée.

La sortie devrait ressembler à ceci…

Donnez à votre apprenant des attentes claires.

Remarquez que… Souvenez-vous que…

Donnez à votre apprenant de nombreux indices pour l'aider à confirmer qu'il est sur la bonne voie et à s'orienter.

Vous avez construit un moteur de stase hylémorphique sécurisé à trois couches…

Décrivez (et admirez, d'une manière douce) ce que votre apprenant a accompli (notez - et non : "vous avez appris...")

Aspect 2: Les Guides pratiques

Il s’agit ici plutôt d’instructions qui guident le lecteur à travers les étapes nécessaires pour résoudre un problème du monde réel. Les guides pratiques sont axés sur les objectifs .

Les guides pratiques ne sont pas seulement importants parce que les utilisateurs doivent être en mesure d'accomplir des tâches : la liste des guides pratiques dans votre documentation aide à cadrer l'image de ce que votre produit peut réellement faire . Une riche liste de guides pratiques est une suggestion encourageante des capacités d'un produit.

S'ils sont bien rédigés et abordent les bons sujets, vous constaterez probablement que les guides pratiques sont les sections les plus lues de votre documentation.

Comment rédiger un bon guide pratique ?

Décrire une séquence d'actions dans un ordre donné

Contrairement à un didacticiel, vous n'avez pas besoin de commencer au début de toute l'histoire et d'amener votre lecteur jusqu'à la fin. Très probablement, votre utilisateur sera également au milieu de quelque chose - il vous suffit donc de fournir un point de départ qu'il sait a tteindre et une conclusion qui répond réellement à une vraie question.

• Résoudre un problème. Tout ce qui est ajouté - une explication inutile, par exemple - distrait à la fois vous et l'utilisateur et dilue la puissance utile du guide.
• Ne pas expliquer les concepts. Une explication ne vous montre pas comment faire quelque chose - donc un guide pratique ne devrait pas essayer d'expliquer les choses. L'explication ici entravera simplement l'action. 
• Soyez flexible, il doit pouvoir s'adapter à des cas d'utilisation réels . Un guide pratique qui est inutile à quelque fin que ce soit, sauf exactement celui que vous avez abordé, est rarement utile.
• Omettre l'inutile. Alors qu'un didacticiel doit être un guide complet de bout en bout, ce n'est pas le cas d'un guide pratique. Il devrait commencer et se terminer à un endroit raisonnable et significatif, et obliger le lecteur à le joindre à son propre travail.

Le langage des guides pratiques

Ce guide vous montre comment…

Décrivez clairement le problème ou la tâche que le guide montre à l'utilisateur comment résoudre.

Si vous voulez x, faites y. Pour atteindre w, faites z.

Utilisez des impératifs conditionnels.

Reportez-vous au guide de référence x pour une liste complète des options.

Ne polluez pas votre guide pratique avec tout ce que l'utilisateur pourrait faire concernant x.

Aspect 3: La référence

Les guides de référence sont des descriptions techniques de la machinerie et de son fonctionnement, axés sur l'information .

Le seul but d'un guide de référence est de décrire, aussi succinctement que possible, et de manière ordonnée. Dans le cas des logiciels, des guides de référence décrivent le logiciel lui-même - API, classes, fonctions, etc. - et comment les utiliser.

Il ne devrait y avoir aucun doute ou ambiguïté dans la référence ; il devrait faire entièrement autorité.

Certains documents de référence (tels que la documentation de l'API) peuvent être générés automatiquement par le logiciel qu'ils décrivent, ce qui est un moyen puissant de s'assurer qu'il reste fidèle au code.

Reprenons la cuisine, si vous cherchez une encyclopédie sur un ingrédient vous y trouverez des informations exactes, à jour et complètes dessus, avec des détails.

Comment rédiger un bon guide de référence ?

• Respecter la structure de la machinerie et refléter la structure du produit, afin que l'utilisateur puisse les parcourir en même temps. Ce qui est important, c'est que l'arrangement logique et conceptuel et les relations au sein du code aident à donner un sens à la documentation.
• Soyez cohérent dans la structure, le langage, la terminologie, le ton
• Ne rien faire d'autre que décrire de manière claire, précise et complète. Si vous souhaitez proposer des explications, créez des liens vers les autres documentations.

• Fournir des exemples, ce sont des moyens précieux de fournir des illustrations qui aident les lecteurs à comprendre la référence, sans être distraits du travail de description

• Soyez précis et à jour. Toute divergence entre la machinerie et votre description de celle-ci conduira inévitablement un utilisateur à s'égarer.

La langue des guides de référence

X est un exemple de y. W doit être initialisé avec z. Cette option fait cela.

Donner des faits sur la machinerie et son comportement.

Les sous-commandes sont : a, b, c, d, e, f.

Répertorier les commandes, les options, les opérations, les fonctionnalités, les drapeaux, les limitations, les messages d'erreur, etc.

Vous devez utiliser un. Vous ne devez pas appliquer b à moins que c. Jamais d.

Fournir des avertissements, le cas échéant.

Aspect 4: L'explication

L'explication clarifie, approfondit et élargit la compréhension du lecteur sur un sujet. C'est une documentation qui aborde un sujet d'un point de vue plus élevé et sous différents angles.

Comment rédiger une bonne explication ?

• Établir des connexions. Lorsque vous écrivez une explication, vous aidez à tisser une toile de compréhension pour vos lecteurs. Établissez des liens avec d'autres choses, même en dehors du sujet immédiat, si cela vous aide.

• Fournir le contexte. Fournissez un arrière-plan et un contexte dans votre explication : expliquez pourquoi les choses sont ainsi - décisions de conception, raisons historiques, contraintes techniques - tirez des implications, mentionnez des exemples spécifiques.

• Discuter des alternatives et des opinions. L'explication peut envisager des alternatives, des contre-exemples ou plusieurs approches différentes à la même question. Vous ne donnez pas d'instructions ou ne décrivez pas des faits - vous ouvrez le sujet à l'examen.

Ne donnez pas d'instructions ou ne fournissez pas de référence technique

Le langage de l'explication

La raison de x est parce qu'historiquement, y…

Expliquer. W est meilleur que z, parce que…

Offrir des jugements et même des opinions, le cas échéant.

Un x dans le système y est analogue à w dans le système z. Cependant…

Fournissez un contexte qui aide le lecteur. Certains utilisateurs préfèrent w (parce que z). Cela peut être une bonne approche, mais…

Pesez les alternatives. Un x interagit avec y de la manière suivante :…

Découvrez les secrets internes de la machinerie, pour aider à comprendre pourquoi quelque chose fait ce qu'il fait.