Success in technical documentation is often measured by how helpful a document is to the end user (or reader). Many technical documents have a section on each page for users to give feedback and suggestions on improving the document. This shows that the primary focus of any technical documentation should be the user.
In this article, we will explore why the end user is so important, how to put their needs first when writing, and how the Diátaxis principle is helpful in such cases.
Understanding User Needs in Technical Documentation
In technical documentation, it is important to understand the needs of your users because your ability to meet these needs will have an impact on the overall success of your documentation.
Put broadly, your users are individuals who use or consume your documentation to gain a better understanding of your product, which may include developer tools, APIs, consumer apps, or even hardware products. These users' needs consist of everything that contributes to helping them understand the documentation and use it to achieve some goals. This can be anything from navigation to the content of the documentation itself.
Despite the broad definition of users above, it is very important to define your target audience and categorize them into primary, secondary, and tertiary targets (or users) and create their user personas as the case may be. Doing this will allow you to think about the possible needs of each category and attempt to solve them.
The needs of your users can also be linked to their intent. Some might only be interested in reference materials, while others might be interested in how-to guides and tutorials. It is very important to create a distinction between these and organize them in easy-to-find ways for your users.
What Is Diátaxis and How Can It Satisfy User Needs
Diátaxis is a framework that focuses on building documentation around the user’s needs. The principles of Diátaxis divide documentation into four categories: tutorials, how-to guides, explanations, and references.
Diátaxis provides solutions related to documentation content, the style or approach to writing the content, and how to organize it for users to find easily.
Many documentation mixes tutorials with how-to guides and places them in places that appear random to the user. This can sometimes make it difficult for the user to navigate the documentation and find answers to their questions.
Diátaxis proposes a solution to this problem by suggesting that you should organize documentation based on the four main categories: tutorials, how-to guides, explanations, and references. This means that all forms of tutorials should be organized together, same with reference materials and the others.
Diátaxis is gaining popularity fast, and many organizations like Canonical have adopted it for their documentation.
Applying Diátaxis for Your Documentation
At its core, Diátaxis defines four categories of documentation: tutorials, how-to guides, explanations, and references. Once you understand how Diátaxis defines and differentiates these categories, you should be able to apply them when building your documentation.
Tutorials
According to Diátaxis, the aim of any tutorial is to help the reader acquire skills and knowledge through practical learning. It is much more about what the reader learns than what they do during the tutorial. For example, if you have to write a tutorial on building a CRUD API in Golang, your aim will most likely be to help the reader learn CRUD as a concept; Golang is just a way for you to help them visualize it.
As much as Diátaxis emphasizes that tutorials should be about what the readers learn and not necessarily what they are doing during the tutorial, it clearly states that you should avoid over-explaining. This is a trap many writers fall into, including myself.
In tutorials, you should aim to give the readers clear, specific instructions and avoid going too deep into concepts that are not directly tied to the aim of the tutorial. If there are multiple ways of doing the same thing, a tutorial is not the best place to say that. Simply focus on giving clear instructions to achieve a goal.
When writing a tutorial, you should also aim to give the readers clear expectations. For instance, at the beginning of your tutorial, you might say something like, “In this tutorial, we will learn how to Deploy a Django application to an AWS EC2 instance“. Declaring this tells your reader exactly what to expect.
Also, in tutorials, you should try to give your readers a sense of doing. You can do this by showing them clear, expected outputs based on some previous steps. This will help them know if they are on the right path or need to repeat a previous step.
How-To Guides
Diátaxis explains that how-to guides are wholly distinct from tutorials. Although they have many similarities, the difference lies in the user needs they serve.
Tutorials focus on helping the user learn and acquire basic competence by giving step-by-step instructions to accomplish a specific goal. On the other hand, how-to guides focus on helping the already competent user achieve a specific goal.
How-to guides usually assume that the user has a good knowledge of the product or technology so it cuts out the noise and focuses squarely on showing the user how to accomplish a task.
How-to guides understand that things won’t always go smoothly for the user in a real-world scenario, so they are usually adaptable to multiple situations. A how-to guide should be useful and applicable in different scenarios and not just a single scenario.
A good title for a how-to guide might be How to Configure a MySQL Database for a Flask Application. This title goes straight to the point. It is safe to assume that the user knows how to use Flask and has configured a different database for it before. The guide can safely cover multiple ways to configure the database without worrying about other unnecessary details like setting up a Flask application from scratch.
Reference Guides
Reference guides are usually information-oriented. They often contain technical details or descriptions of the product.
The Diátaxis documentation likens a reference guide to a map. When you look at a map, it might immediately tell you about a lake in some place, but it doesn’t give you too much information such as how the lake got there or if a Mr. John has a building close to it. The map simply shows you the layout of the landscape to help you efficiently navigate it.
Reference guides such as API references should be like a map. They should mention the necessary details such as the endpoints, required and option fields, response examples, etc but other explanations should be kept for a different guide.
Explanations
The goal of explanation guides is to impart the user with understanding of a product or tool. An explanation guide is at liberty to explain how a part of your product connects to another or how a specific part of your tool works under the hood. The idea is to help your users truly understand what the product does on a technical level
For example, if you have a payment platform, you can have explanation materials to explain how your transfer system works under the hood and what the developer needs to do in order to properly integrate it. Things like creating a recipient or a quote to properly make a transfer should come under explanations.
Conclusion
The Diátaxis framework is a really useful tool if you can apply it properly to your documentation. It can get confusing really quickly when you follow the principles for the first time, but you should be good after a few attempts.
Can you guess what kind of article this is? Reference, explanation, tutorial or how-to? Let’s discuss it in the comments!
Resources
You might find the following resources useful in your journey to understand Diátaxis and apply its principles:
Cover Image Credit: Diátaxis’ official documentation
Top comments (0)