We have all consulted documentation at some point in our interaction with software. Whether you were wondering about how to integrate MPESA’s APIs, installing some Python package, or simply reading about how Netflix works.
Probably, most of the documentation you have seen are badly structured and/or targeted at the wrong user or use case. As a beginner technical writer, I would have vehemently opposed this take. Does it mean I suck at my job, for example? Not really. The problem is not with the writing but with the approach toward producing software documentation. Enter the Diátaxis framework.
All models are wrong, but some are useful.
The Diátaxis framework: What is it?
Diátaxis is a framework that can be used to structure technical documentation. In Diátaxis, documentation can be split into four modes: tutorials, how-to guides, technical reference, and explanation. At the core of Diátaxis is the idea that documentation is not one but four distinct things that serve different user needs, have unique purposes, and require varying approaches while being written.
Tutorials
Tutorials are lessons that take a reader by the hand through a series of steps to complete a project of some kind. They are learning-oriented and lie at the intersection of practice and study.
Under the instruction of the instructor, the reader will execute a series of actions to achieve a task. A tutorial should look and feel like a lesson as its goal is to provide a successful learning experience. It is up to the teacher to determine the end and the actions, but the end has to be achievable and meaningful to an absolute beginner.
Example tutorial page: Ubuntu Core
How-to guides
How-to guides are similar to a recipe that can be followed to achieve a particular goal. They are goal-oriented and assume that the reader has some level of familiarity with the software.
How-to guides lie at the intersection of work and practice in that they target users who are getting something done while at work and, in doing so, the reader is applying their knowledge to a real task or problem. In this case, what the reader needs is to be shown the steps they should take and not a learning experience as with tutorials.
It is the obligation of the user to know what they want to get done and to apply the guide to meet their needs as dictated by the situation.
Example how-to guide page: Gatsby
Technical reference
Reference materials provide technical descriptions of the machinery and how to operate it. They only have one job: to describe, for instance, the key classes, functions, APIs, structural layout fields, attribute and methods, and how to use them.
While the content of tutorials and how-to guides are led by the needs of the user, reference materials are led by the product it describes. They lie at the intersection of work and theory, whereby the user at work needs to look up information about the product with which they are working.
Example technical reference page: Gatsby
Explanations
Explanations, or discussions, clarify and illuminate a given topic. They are understanding-oriented and broaden the documentation's coverage of a topic. They lie at the intersection of study and theory, where they join things together and allow the reader to make sense of a topic away from the product itself.
Explanations can also be referred to as Discussion, Background, Conceptual Guide, or Topics.
Example explanation page: Divio
Restructuring JupyterHub’s documentation using Diátaxis: What is involved?
Here is the blog post introducing myself, the other JupyterHub’s Outreachy interns, and our projects. For my project, specifically:
This project will focus on a refactoring of the documentation for the JupyterHub package. We will begin by performing a review of the present documentation, categorise these into the diataxis framework, and then restructure the documentation files in the repository. Once we have transformed the documentation into this framework, it will be much easier to identify missing and unclear documentation (those that were difficult to categorise). We can then begin to curate resources that can fill the gaps and improve documentation that is not specific enough.
In sum, my work can be split into four main areas:
Performing a review of the present documentation.
Categorizing the documentation into the Diataxis framework.
Restructuring the documentation files in the repository.
Identify missing and unclear documentation.
In the next post, I will write about the project's progress.