https://diataxis.fr/

[ ] [ ]
Hide navigation sidebar
Hide table of contents sidebar
Toggle site navigation sidebar
 
Diataxis
Toggle Light / Dark / Auto color theme
Toggle table of contents sidebar
 
Logo

  * Home

  * Applying Diataxis
  * Tutorials
  * How-to guides
  * Reference
  * Explanation
  * The compass
  * Workflow

  * Understanding Diataxis
  * Foundations
  * The map
  * Quality
  * Tutorials and how-to guides
  * Reference and explanation
  * Complex hierarchies

  * Colophon

[                    ] 
Back to top
Toggle Light / Dark / Auto color theme
Toggle table of contents sidebar

DiataxisP

A systematic approach to technical documentation authoring.

---------------------------------------------------------------------

Diataxis is a way of thinking about and doing documentation.

It prescribes approaches to content, architecture and form that
emerge from a systematic approach to understanding the needs of
documentation users.

Diataxis, from the Ancient Greek diataxis: dia ("across") and taxis
("arrangement").

Diataxis identifies four distinct needs, and four corresponding forms
of documentation - tutorials, how-to guides, technical reference and
explanation. It places them in a systematic relationship, and
proposes that documentation should itself be organised around the
structures of those needs.

Diataxis

Diataxis 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, Diataxis 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.

---------------------------------------------------------------------

ContentsP

This website is divided into two main sections, to help apply and
understand Diataxis.

Start here. These pages will help make immediate, concrete sense of
the approach.

  * Applying Diataxis
  * Tutorials
  * How-to guides
  * Reference
  * Explanation
  * The compass
  * Workflow

This section explores the theory and principles of Diataxis more
deeply, and sets forth the understanding of needs that underpin it.

  * Understanding Diataxis
  * Foundations
  * The map
  * Quality
  * Tutorials and how-to guides
  * Reference and explanation
  * Complex hierarchies

---------------------------------------------------------------------

Diataxis is proven in practice. Its principles have been adopted
successfully in hundreds of documentation projects.

    At Gatsby we recently reorganized our open-source documentation,
    and the Diataxis framework was our go-to resource throughout the
    project. The four quadrants helped us prioritize the user's goal
    for each type of documentation. By restructuring our
    documentation around the Diataxis framework, we made it easier
    for users to discover the resources that they need when they need
    them.

    --Megan Sullivan

    While redesigning the Cloudflare developer docs, Diataxis became
    our north star for information architecture. When we weren't sure
    where a new piece of content should fit in, we'd consult the
    framework. Our documentation is now clearer than it's ever been,
    both for readers and contributors.

    --Adam Schwartz

 
Next
Applying Diataxis
Copyright (c) Daniele Procida
On this page

  * Diataxis
      + Contents