Diátaxis¶
Une approche systématique à la rédaction de documentation technique.
Diátaxis est une manière de penser et de réaliser la documentation.
It prescribes approaches to content, architecture and form that emerge from a systematic approach to understanding the needs of documentation users.
Diátaxis identifie quatre besoins distincts et quatre formes de documentation correspondantes - tutoriels, guides pratiques, référence technique et explications. Il les place dans une relation systématique et propose que la documentation elle-même soit organisée autour de la structure de ces besoins.
Diátaxis solves problems related to documentation content (what to write), style (how to write it) and architecture (how to organise it).
As well as serving the users of documentation, Diátaxis has value for documentation creators and maintainers. It is light-weight, easy to grasp and straightforward to apply. It doesn’t impose implementation constraints. It brings an active principle of quality to documentation that helps maintainers think effectively about their own work.
Contents¶
The best way to get started with Diátaxis is by applying it after reading a brief primer.
These pages will help make immediate, concrete sense of the approach.
This section explores the theory and principles of Diátaxis more deeply, and sets forth the understanding of needs that underpin it.
Diátaxis is proven in practice. Its principles have been adopted successfully in hundreds of documentation projects.
Diátaxis has allowed us to build a high-quality set of internal documentation that our users love, and our contributors love adding to.
—Greg Frileux, Vonage
Avec l’équipe de Gatsby, nous avons récemment réorganisé notre documentation libre et ouverte, et le cadre de Diátaxis a été notre ressource privilégiée tout au long du projet. Les quatre quadrants nous ont aidés à mettre de l’avant l’objectif de l’utilisateur pour chaque type de documentation. En restructurant la documentation selon le cadre de Diátaxis, nous avons facilité la découverte de ressources pertinentes pour l’utilisation du produit et ce, au moment où ces ressources sont nécessaires.
Lors de la refonte de la documentation de développement de Cloudflare, Diátaxis est devenu notre étoile du nord pour l’architecture de l’information. Lorsque nous n’avions pas la certitude de l’endroit où placer un nouveau morceau de contenu, nous consultions ce cadre. Notre documentation est maintenant plus claire que jamais, à la fois pour les personnes qui la lisent et pour celles qui y contribuent.