Outils Utiles
Quel outil choisir pour votre documentation technique ?
Vous ne savez pas quel outil utiliser pour votre documentation technique ? Découvrez le comparatif ultime entre Docusaurus et ses concurrents.
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:
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.
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.
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.
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.
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.
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 :
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.
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.
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.
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...")
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.
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.
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.
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.
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.
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.
Ne donnez pas d'instructions ou ne fournissez pas de référence technique
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.
