Diátaxis – une approche systématique de la rédaction de documentation technique

• Diátaxis est un concept qui propose une approche systématique de la rédaction de documentation technique. Cette approche part d’une compréhension structurée des besoins des utilisateurs de la documentation et propose une manière d’aborder le contenu, la structure et la forme.
• Issu du grec ancien, Diátaxis identifie quatre besoins distincts et les formes documentaires correspondantes : tutoriels, guides pratiques, références techniques et explications. Il propose d’organiser la documentation selon la structure de ces besoins.
• Diátaxis répond aux questions liées au contenu (quoi écrire), au style (comment écrire) et à la structure (comment organiser).
• Il a de la valeur non seulement pour les utilisateurs de la documentation, mais aussi pour ses auteurs et ses mainteneurs. Il est léger, facile à comprendre et simple à appliquer. Il n’impose pas de contraintes de mise en œuvre et fournit des principes concrets pour améliorer la qualité de la documentation.

Contenu

• Ce site web est divisé en deux grandes sections pour aider à appliquer et à comprendre Diátaxis.

  • Commencez ici. Ces pages aident à comprendre l’approche de manière immédiate et concrète.
    • Appliquer Diátaxis
    • Tutoriels
    • Guides pratiques
    • Référence
    • Explication
    • Boussole
    • Flux de travail
  • Cette section explore plus en profondeur la théorie et les principes de Diátaxis, et présente une compréhension des besoins qui les sous-tendent.
    • Comprendre Diátaxis
    • Fondements
    • Carte
    • Qualité
    • Tutoriels et guides pratiques
    • Référence et explication
    • Hiérarchies complexes

• Diátaxis est un principe éprouvé dans la pratique. Il a été adopté avec succès dans des centaines de projets de documentation.

  • Chez Gatsby, le framework Diátaxis est utilisé comme ressource principale pour restructurer la documentation open source. Les quatre quadrants aident à prioriser les objectifs des utilisateurs pour chaque type de documentation.
  • Lors de la refonte de la documentation développeur de Cloudflare, Diátaxis est devenu l’étoile polaire de l’architecture de l’information. En se référant au framework pour décider où placer les nouveaux contenus, la documentation est devenue plus claire à la fois pour les lecteurs et pour les contributeurs.

[GN⁺]

Commentaires sur Hacker News

• Un utilisateur souligne qu’il est important de comprendre qu’il n’est pas nécessaire de transmettre toutes les informations en une seule fois. Il est utile de rédiger l’information de différentes manières pour différents lecteurs

• Il explique que l’application du framework Diátaxis à la documentation de Sequin a amélioré le flux de la documentation. Cependant, il remarque que la documentation de Diátaxis elle-même est quelque peu difficile à suivre et verbeuse

  • Il l’explique à l’aide d’une analogie avec le processus d’achat d’un ustensile de cuisine
    • On commence par un tutoriel de « démarrage rapide » pour voir l’usage général
    • Découvrir comment l’utiliser pour un plat précis correspond au « how-to »
    • Si l’on veut aller plus loin, on consulte des documents de référence
    • Si l’on veut comprendre les principes scientifiques de la cuisson sous pression, on lit des documents explicatifs

• Des rédacteurs de documentation technique mentionnent que Diátaxis ressemble à DITA. Cependant, ils expliquent qu’il peut passer à côté des besoins des utilisateurs et qu’il peut être nécessaire de découper l’information en petits morceaux pour en permettre la réutilisation

• Un utilisateur ayant développé une application SwiftUI estime que la documentation technique moderne est mal traitée et affirme que la documentation doit prendre en compte deux aspects : celui des mainteneurs et celui des utilisateurs

• Il est mentionné que Diátaxis est utile pour structurer la documentation, mais qu’une application trop rigide peut devenir un piège

• Il est expliqué que la véritable valeur de Diátaxis réside dans la simplification de la manière d’écrire la documentation. Il est important de rédiger la documentation en fonction des besoins de chaque utilisateur

• Il est mentionné que le graphique de divio est plus intuitif, mais que Diátaxis fournit une documentation plus complète

• Il est expliqué qu’après l’adoption de Diátaxis, la documentation technique s’est nettement améliorée, et que la responsabilité des pages ainsi que des révisions périodiques ont contribué à une documentation réussie

• Il est mentionné que le framework Diátaxis offre une structure simple et facile à comprendre, ce qui le rend utile pour la rédaction de documentation technique

• Une personne rédige actuellement la documentation de Logdy avec Diátaxis et demande des avis sur l’utilité de cette méthode pour documenter un produit logiciel. Elle explique avoir efficacement montré comment utiliser le produit à travers des billets de blog