If you're a technical writer with an interest in software documentation, your obvious goal would be to keep figuring out ways to be a better documentarian and create documentation in a way that users would continually find useful. It also means that in your search, you'd come across industry-standard recommendations and guides.
It is such adventures that led me to find out about the Diataxis framework. Created in 2017 by Daniele Procida, a senior technical writer currently at Ubuntu, it is a very popular and widely accepted guide for creating documentation. It is used by organizations like Gatsby, Django, etc. You can find the whole list here.
I read through it, and I'd be writing about some of the things I learned in this article.
The Aim Of Diátaxis
Diátaxis focuses on solving the problem of structure in the documentation. Basically the "what goes where" and "how do we represent this information" dilemma of crafting documentation. It is usually structured in four ways: Tutorials, How-to-guides, Explanations and References, and posits that "what we call documentation is fundamentally not one thing, but four".
Tutorials
"Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. Tutorials are learning-oriented."
This a practical guide. It's supposed to show a learner how to use something, and help them develop basic competence in said resource or tool. This is a learning experience for a user and is regarded as the trickiest part. Why?
It is your job as the tutor to make the experience as seamless as possible for the learner while making it applicable to a very diverse audience. This can be an uphill task and sometimes this could mean completely revamping the whole text as frequently as possible, compared to other parts that may need changes very infrequently.
Nevertheless, your goal at the end of this section is to enable your user to walk away with the feeling of doing something, and a practical example to show for following your steps.
How-To-Guides
"How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal-oriented."
These guides are written to teach enough to get things done. The end goal is to get you to achieve something. The writer assumes you have prior knowledge of the basics and delves into how to perform a task using your knowledge.
Although they seem similar to tutorials, they are more specific; they have an end goal in mind. It is very common to confuse how-to guides with tutorials. So, a key way to differentiate them is to always keep in mind that tutorials focus more on the audience knowing or understanding stuff and how-to guides focus on the doing.
Reference Guides
"Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented."
These are resources for consulting. They are straight to the point, orderly and authoritative. Readers should trust the guides as endpoints for whatever information they're searching for.
It is not a learning material in the way that a tutorial is, neither is it a doing material like a how-to guide is. It is material for reference, either to look up and gather further information on existing knowledge or to cement already known facts.
In essence, it is descriptive, it is authoritative, and it does not replicate a tutorial or how-to guide.
Explanations
"Explanation is discussion that clarifies and illuminates a particular topic. Explanation is understanding-oriented."
Explanation guides are the about of a project or a concept or whatever subject. They are discussion material and give room to let your audience think about the subject matter from a higher level of thinking. It allows for comparing alternatives or various ways to approach a particular topic.
It does not teach you what to learn, how to do or act as a reference guide. What it does, is shed more light on a topic, explore the topic and allow you to discuss and view the topic from various perspectives.
It does things other parts of the documentation do not do.
Conclusion
When writing documentation properly indicate what type of documentation it is you're about to write about as this helps narrow your focus and not mix up the different forms.
By extension, this also directs your users accordingly and helps them know exactly where to find the kind of information or resource they might be looking for. If something they're looking for isn't in a particular document, it should be obvious it is not there because there's only one place it could be.
Documentation is putting your user's needs first, doing this makes it easier for users and in the long run, would make your product a first choice amongst your target audience.
This is a very summarised version of all that the diàtaxis framework is. Please read more about it here.
If you got value from this or just have general thoughts and comments concerning this, please feel free to connect with me on Twitter or LinkedIn. I'd love to hear from you, and I love talking about docs, so don't worry you won't bore me or anything of the sort.
Until next time,
May the force good documentation be with you.