Complete but never finished - Better documentation with Diátaxis

Authoring documentation has been a constant struggle for me. I find it easy enough to start writing, but grappling at what topics to include, how to organise the topics in a sensible way is paralysing. The result is almost always a hodgepodge of guides, references and explanations. Throw in some random opinions here and there and the smörgåsbord is complete.

Worse, whenever I get back to the documentation I made, I get confused navigating around it. I can only imagine how my intended readers feel. There has to be a better way.

As chance would have it, while exploring, Open Food Facts (OFF), I stumbled upon Diátaxis, a documentation framework that OFF uses to structure their documentation. I got hooked after reading through a few paragraphs. I liked its simplicity. Pretty straightforward and easier to follow, the framework author, Daniele Procida, explains the points very well too. Most importantly, it describes my current predicament accurately, why it came to be that way and what can be done about it.

So, what is Diátaxis?

Diátaxis is a systematic approach for technical documentation authoring, providing a framework for understanding documentation users' needs, authoring directions and evaluating documentation quality.

It doesn't require custom tooling, no difficult words to unpack, and no need to implement a complicated structure.

It advances the idea that fundamentally, documentation as we know it, is not one thing but is actually four!  The four modes are tutorials, how-to guides, references and explanations.

Each of these, while interrelated, requires different approaches of creation and serves a different purpose. The understanding of the implication of this, influences the way the content is formulated, leading to an easier creation and maintenance.

The four modes of documentation

Diátaxis discusses each of the four modes extensively, including a very good summary in tabular form. Below are just some of the salient points that lit lightbulbs on my head and hopefully, yours too.

Tutorials

Can you teach me to...?

This is the learning-oriented mode that takes the form of a lesson, designed to get a newcomer started. With a clear set of objectives and through a series of logical, repeatable steps, the user is taken on a journey to achieve competence in a product. A carefully laid-out path is contrived so that the reader encounters the actions, tools and concepts in a product they need to be familiarised with.

Upon completion of the tutorial, the reader will have acquired the practical skill needed to be successful in a product. Learning by doing is the principle at work.

How-to guides

How do I...?

Taking on the form of a series of steps, it is the task-oriented mode that aims to guide and demonstrate to the user how a specific real-world problem is solved. A certain level of competence is assumed from the user in order for them to perform the requisite tasks. Unforeseen conditions are expected to occur so alternatives must be prepared in the classical "if this, then that, else" format.

Upon completion, the reader will have resolved the immediate problem at hand.

Reference

What is...?

Being the information-oriented mode, a reference contains factual and objective facts meant to inform the user about the inner workings of a product. The reader is expected to consult the reference so the content should be authoritative but neutral, accurate and comprehensive. Equally important is a provision of illustrations and examples such as showing how a functionality can be used, what commands are available or what limitations they need to be aware of.

Explanation

Why...?

With explanations, the aim is to provide, among other things, context, discourse and history behind the decisions that made the final product. Considered as the understanding-oriented mode, the content is meant to provide a user, clarity on a topic

to help deepen or broaden a reader's grasp of it.

For this intention, an explanation can take on the form of a discussion where different perspectives can be examined, historical reasons can be brought forward and potential alternatives can be explored.

Conflation equals chaos

As stated by the framework author, the conflation of the above-mentioned modes is what leads to many a chaotic documentation structure. Since there is an innate connection among the different modes, it is relatively easy to mix up one mode of content with another. Without discipline, this snowballs quite quickly.  

The most obvious of this struggle is mistaking tutorials over how-to guides. A thorough disccusion of their distinction is provided by the framework author that certainly removes all the confusion. I go over some of the points below.

Tutorial and how-to guide compared

At first glance, these two seem to be the same. According to Diátaxis, both describe practical, sequenced steps that a reader follows, with a definite end goal in mind. There is an expectation that the reader is hands-on. Finally, both concepts are not supposed to explain or convey information.

While it may be easy to mistake one over the other, Diátaxis contends that they are wholly distinct from one another. To distinguish them, the following questions must be asked in order to identify what need is being served:

Are the readers at study or are they at work?

The answer to this question serves as the dividing line between the two.

After all, a tutorial provides a learning experience while a how-to guide provides concrete steps to complete a real-world task. A tutorial is safe, in the sense that a carefully planned path is made for the reader in order for them to succeed while a how-to guide is meant to tackle actual tasks with genuine consequences. Furthermore, a tutorial needs to be explicit with what it requires from the reader, like what commands to enter and where. A how-to guide infers that this knowledge is already known.

In short, a tutorial serves the reader who is acquiring knowledge. They are striving to become competent. A how-to guide on the other hand serves the reader who is already competent and is applying the knowledge. They are working on a specific task in the real world.

Addressing root of the problem

While knowing the different documentation modes helps with shaping the content, the problem of structure remains. It is the bane, documentation authors such as me, struggle with on a regular basis.

Instead of providing a checklist of things on how to concretely structure documentation, the framework provides a strategy on how to effectively arrive at it. It suggests that a methodical and thorough understanding of the users' documentation needs is the key.

Since the framework is well-suited to a type of content about

a practical craft, a technical skill - such as the use of a product,

there should be an expectation that our target users are going to interact with our documentation with the aim of becoming an expert in a skill. This is the paramount need that must be met in order to have a more effective documentation.

In this journey to becoming an expert, our users will consume documentation content in various ways and at different instances, to seek guidance on a particular aspect of a product.

This cycle of documentation needs, emanating from their cycle of interaction with the product, enables the user to hone their skill. As authors, we must recognise that this requires not only an ability for them to apply it practically but also for them to get a firm grasp of the concepts. So, we evaluate our documentation against these two important axes of knowledge

• what they should contain, theory or practice
• and what they should serve, acquisition or application of knowledge.

Combining these two underlying concepts of cycle of interaction and axes of knowledge with the four modes, yields a strategy that documentation authors can utilise in formulating appropriate content and in constructing a sensible structure around documentation.

This map of distinct types can then be used whenever there is uncertainty regarding a particular piece of documentation. Authors can look up to it for guidance.

Pragmatic application

Diátaxis is a guide, not a plan. It helps us on how to be deliberate in shaping our documentation. It prescribes a workflow that encourages an iterative, and snowballing approach to applying it. Diligently following the process below, should promote an organic growth of our documentation that starts from within.

• Choose something - any piece (a sentence, a paragraph, a page) of the documentation
• Assess it - consider this thing critically, challenge it via the Diátaxis principles.
  
  
  
  
• Decide what to do - What single next action will produce an immediate improvement here?
• Do it - Complete that next single action, and consider it completed - i.e. publish it

By its very nature, it fits right in with an agile way of working. Hence, piggybacking on this workflow by expressly including it in our definition of done enables us to avoid information within our documentation becoming obsolete.

Complete, never finished

The biggest take-away I got from learning about this framework is treating our documentation like a living organism.

It is an artefact that is never finished as it must be continuously adapted and updated in tandem with the ever-changing user needs and business requirements.

On the other hand, it should be complete enough to be entirely useful to the users at any given time. The information within it is intact but ready to be expanded as soon as the need arises.

Learn more

The Diátaxis documentation framework is a work of Daniele Procida. Much and more can be learned by visiting the main site and reading through the whole thing. Should you want to explore the source material itself, a git repository is available for that. Diátaxis has already been adopted by  a good number of products and organizations, some of which I recognise and list below:

1. Cloudflare Workers documentation
2. BBC News Labs
3. LootLocker
4. Wechaty
5. Zalando (internal)
6. Tesla Motors (internal)

I hope this inspired you, as it did me, to take a thorough review of your documentation and consider how you can adopt Diátaxis into your documentation strategy.

Cheers!