Commencer ici - Diátaxis en cinq minutes¶

Vous n’avez pas à lire tout ce site pour comprendre Diátaxis, ni pour commencer à l’utiliser en pratique. En fait, je vous le déconseille même. La meilleure façon de débuter avec Diátaxis est de l’appliquer - à quelque chose, si petit soit-il.

Lisez cette page pour une brève introduction. Chaque section contient des liens vers du contenu plus approfondi ; consultez-le lorsque vous en avez besoin - quand vous êtes en plein travail, ou que vous réfléchissez aux problèmes de documentation que vous avez rencontrés.

Les quatre types de documentation¶

L’idée centrale de Diátaxis est qu’il existe fondamentalement quatre types identifiables de documentation, qui répondent à quatre besoins différents. Les quatre types sont : tutoriels, guides pratiques, référence et explication. Chacun a un but différent et se rédige à sa façon.

Tutoriels¶

Un tutoriel est une leçon, qui guide l’élève par la main à travers une expérience d’apprentissage. Un tutoriel est toujours pratique : l’utilisateur agit, sous la direction d’un enseignant. Un tutoriel est conçu autour d’une rencontre que l’apprenant peut comprendre, dans laquelle l’enseignant est responsable de sa sécurité et de sa réussite.

Une leçon de conduite est un bon exemple de tutoriel. L’objectif de la leçon est de développer les compétences et la confiance de l’élève, et n’est pas d’aller de A à B. Un exemple logiciel pourrait être : Créons un jeu simple en Python.

L’utilisateur apprendra par ce qu’il fait - et pas parce que quelqu’un a essayé de lui enseigner.

Dans le cas de la documentation, la difficulté particulière est que l’enseignant est condamné à être absent, et n’est pas là pour surveiller l’apprenant et corriger ses erreurs. L’enseignant doit, d’une manière ou d’une autre, trouver un moyen d’être présent uniquement par l’instruction écrite.

Guides pratiques¶

Un guide pratique traite un objectif ou un problème réel, en fournissant des instructions pratiques pour aider l’utilisateur qui se trouve dans cette situation.

Un guide pratique s’adresse toujours à un utilisateur déjà compétent, supposé capable de se servir du guide pour accomplir son travail. Contrairement à un tutoriel, le guide pratique concerne le travail et non l”étude.

Un guide pratique pourrait être : Comment conserver le film nitrate de cellulose (en photographie cinématographique) ou Comment configurer le profilage des frames (dans le domain logiciel). Ou même : Résoudre les problèmes de déploiement.

Référence¶

Les guides de référence contiennent la description technique — des faits — dont l’utilisateur a besoin pour agir correctement : des informations précises, complètes et fiables, sans distraction ni interprétation. Ils contiennent du savoir propositionnel ou théorique, et pas des guides d’action.

Comme un guide pratique, la référence sert l’utilisateur au travail, et il revient à l’utilisateur d’être suffisamment compétent pour l’interpréter et l’utiliser correctement.

Le contenu de référence est neutre. Elle ne se préoccupe pas de ce que fait l’utilisateur. Une carte marine peut être utilisée par un navigateur pour tracer une route, mais tout aussi bien par un juge d’instruction.

Lorsque c’est possible, l’architecture de la référence devrait refléter la structure ou l’architecture de ce qu’elle décrit — tout comme une carte. Si une méthode fait partie d’une classe qui appartient à un certain module, alors nous devrions nous attendre à voir la même relation dans la documentation.

Explication¶

Les guides d’explication fournissent du contexte et des arrière-plans. Ils répondent au besoin de comprendre et d’embrasser une perspective plus large. L’explication relie les questions, et aide à répondre à la question pourquoi ?

L’explication doit souvent tourner autour de son sujet et l’aborder sous différents angles. Elle peut contenir des opinions et prendre des positions.

Comme la référence, l’explication relève du savoir propositionnel plutôt que de l’action. Toutefois, son but est de servir l’étude de l’utilisateur — comme le font les tutoriels — et pas son travail.

Souvent, les auteurs de tutoriels, soucieux que leurs élèves connaissent les choses, surchargent leurs tutoriels d’explications distrayantes et inutiles. Il serait bien plus utile de fournir à l’apprenant explication minimale (« Ici, nous utilisons HTTPS parce que c’est plus sûr ») puis de pointer vers un article approfondi (Communication sécurisée à l’aide du chiffrement HTTPS) pour le moment où l’utilisateur sera prêt.

La carte Diátaxis¶

Les quatre types de documentation et les relations entre eux peuvent être résumés dans la carte Diátaxis.

Diátaxis n’est pas qu’une liste de quatre choses différentes, mais un agencement conceptuel de ces choses. Il montre comment les quatre types de documentation sont liés entre eux et se distinguent les uns des autres.

Franchir ou brouiller les frontières décrites dans la carte est au cœur d’une foule de problèmes de documentation.

La boussole Diátaxis¶

Comme on le voit sur la carte :

les tutoriels et les guides pratiques concernent ce que l’utilisateur fait (action)
la référence et l’explication portent sur ce que l’utilisateur sait (cognition)

D’autre part :

les tutoriels et l’explication servent l”acquisition de compétence (l”étude de l’utilisateur)
les guides pratiques et la référence servent l”application de compétence (le travail de l’utilisateur)

Mais une carte ne vous dit pas ce qu’il faut faire — c’est de la référence. Pour guider votre action, il vous faut un autre type d’outil, dans ce case, une boussole Diátaxis.

La boussole est utile de deux manières différentes.

Lorsqu’on crée de la documentation, elle permet de clarifier ses propres intentions et à s’assurer qu’on fait bien ce qu’on croit faire.

Lorsqu’on examine de la documentation, elle permet de comprendre ce qui s’y passe et fait ressortir les problèmes.

La boussole est bien moins frappante que la carte, mais quand vous vous cassez la tête au travail sur un problème de documentation, c’est elle qui vous aidera à avancer.

Si le contenu…	…et sert… de l’utilisateur	…alors il doit appartenir à…
informe l’action	acquisition de compétence	un tutoriel
informe l’action	application de compétence	un guide pratique
informe la cognition	application de compétence	référence
informe la cognition	acquisition de compétence	explication

Travailler¶

Il existe un flux de travail très simple pour Diátaxis.

Considérez ce que vous voyez dans la documentation, sous vos yeux (ce qui pourrait n’être littéralement rien, si vous n’avez pas encore commencé).
Demandez : y a-t-il un moyen de l’améliorer ?
Décidez d”une action à y mener tout de suite, aussi minime soit-elle, qui l’améliorerait.
Faites-le.

Puis répétez.

C’est tout.

Faites ce que vous voulez¶

Vous pouvez faire ce que vous voulez avec Diátaxis. Vous n’êtes pas obligé d’y croire et il n’y a pas d’examen. C’est une approche entièrement pragmatique. Je pense qu’elle est vraie, mais ce qui compte, c’est qu’elle aide en réalité les gens à créer une meilleure documentation. Si vous y trouvez une idée ou un éclairage qui vous semble valable, servez-vous.

Il existe une théorie amplement développée autour de Diátaxis, mais vous n’avez pas à y souscrire, ni même de la lire. Diátaxis n’exige pas qu’on s’engage à la poursuivre jusqu’à son terme.

Vous pouvez vous contenter d’une seule action, tout de suite : même si vous ne faites plus jamais rien d’autre, vous aurez au moins cette amélioration à votre actif. (À l’usage, chaque action accomplie vous mettra sur la piste de la suivante — il suffit de continuer.)

Commencer¶

À ce stade, vous avez lu tout ce qu’il vous faut pour débuter avec Diátaxis.

Vous pouvez lire davantage si vous le souhaitez, et à terme vous devriez probablement, mais vous tirerez le meilleur parti des conseils de ce site lorsque vous l’abordez avec un problème ou une question. C’est à ce moment-là qu’il prend vie.