What is documentation?

Just as the role of a technical writer has evolved from being an administrative assistant’s part-time task of entering an engineer’s notes into Word to being a full-time position with docs treated as code, so has the concept of what exactly documentation should be.

Diátaxis

Anyone who has seriously worked in this field has encountered Daniele Procida’s technical documentation framework that proposes there are actually four distinct types of documentation:

  • Tutorials

  • How-to guides

  • Explanation

  • Reference

The Diátaxis site provides a wealth of information showing how writing documentation to fit into each of these categories is the most customer-centric approach.

Implementing Diátaxis

One of the best implementation examples of Diátaxis is Gatsby’s documentation. Megan Sullivan, a senior software engineer at Gatsby, produced a video, GatsbyCamp Fall | Docs for Everyone!, that every technical writer should watch. The five tips she presents are:

  1. Expose the architecture (in this case, Diátaxis)

  2. Set the stage

  3. Let readers choose

  4. Check for understanding

  5. Get user feedback

The thing I really like about the Diátaxis documentation framework is that it prioritizes the user’s goal.
— Megan Sullivan