A systematic framework for technical documentation authoring.

Close

Framework Image

The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.

The framework identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation.

Each of these modes (or types) answers to a different user need, fulfils a different purpose and requires a different approach to its creation.

Technical documentation should be structured explicitly around these four types, and should keep them all separate and distinct from each other.

Explanation   Top

Explanation is discussion that clarifies and illuminates a particular topic. Explanation is understanding-oriented. (Docs)

It’s not concerned with what the user might be doing, like tutorials and how-to guides. It’s not a close-up view of the machinery, like reference material. It’s documentation that approaches a topic from a higher perspective, and from different angles.

Explanation and its boundaries

It’s not always easy to write good explanatory material. Where does one start? It’s also not clear where to conclude. There is an open-endedness about it that can give the writer too many possibilities.

Tutorials, how-to-guides and reference are all clearly defined in their scope by something that is also well-defined: by what you need the user to learn, what task the user needs to achieve, or just by the scope of the machine itself.

In the case of explanation, it’s useful to have a real or imagined why question to serve as a prompt. Otherwise, you simply have to draw some lines that mark out a reasonable area and be satisfied with that.

Writing good explanation

Make connections

When writing explanation you are helping to weave a web of understanding for your readers. Make connections to other things, even to things outside the immediate topic, if that helps.

Provide context

Provide background and context in your explanation: explain why things are so - design decisions, historical reasons, technical constraints - draw implications, mention specific examples.

Talk about the subject

Explanation guides are about a topic in the sense that they are around it. Even the names of your explanation guides should reflect this; you should be able to place an implicit (or even explicit) about in front of each title. For example: About user authentication, or About database connection policies.

Discuss alternatives and opinions

Explanation can consider alternatives, counter-examples or multiple different approaches to the same question. You’re not giving instruction or describing facts - you’re opening up the topic for consideration. It helps to think of explanation as discussion: discussions can even consider and weigh up contrary opinions.

Don’t instruct, or provide technical reference

One risk of explanation is that other things can tend to creep in. Explanation should do things that the other parts of the documentation do not. It’s not the place of an explanation to instruct the user in how to do something. Nor should it provide technical description. These functions of documentation are already taken care of in other sections.

It’s not always easy to write good explanatory material. Where does one start? It’s also not clear where to conclude. There is an open-endedness about it that can give the writer too many possibilities.

The Language of Explanation

The reason for x is because historically, y…

Explain.

W is better than z, because…

Offer judgements and even opinions where appropriate..

An x in system y is analogous to a w in system z. However…

Provide context that helps the reader.

Some users prefer w (because z). This can be a good approach, but…

Weigh up alternatives.

An x interacts with a y as follows:…

Unfold the machinery’s internal secrets, to help understand why something does what it does.

Tutorials   Top

Introduction to 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. (Docs)

A tutorial must help a beginner achieve basic competence with a product, so that they can go on to use the product for their own purposes.

A tutorial also needs to show the learner that they can be successful with the product - by having them do something both meaningful and attainable.

A tutorial in other words is a lesson - a lesson concerned with learning how rather than learning that, because it’s concerned with skill: practical, not theoretical knowledge.

Having completed a tutorial, the learner should be in a position to start to make sense of the rest of the documentation, and the product itself.

For a product, tutorials turns new learners into users. An inadequate tutorial can prevent a project from acquiring new users.

The Tutorial as a Lesson

A lesson entails a relationship between a teacher and a pupil. In all learning of this kind, learning takes place through what the the pupil does.

Any facts and explanations that are presented in teaching are almost irrelevant to what the pupil will learn - what matters is what the teacher gets the pupil to do.

For our purposes, a lesson is a learning experience. If you are not providing your learner with a learning experience, your tutorial isn’t doing the job it needs to.

Obligations of the teacher

The teacher has responsibility, for what the pupil is to learn, what the pupil will do in order to learn it, and for the pupil’s success. The only responsibility of the pupil is to be attentive and to follow the teacher’s directions as closely as they can. There is no responsibility on the pupil to learn, understand or remember - the learner’s only obligation in this contract is to do things as directed.

At the same time, the exercise you put your pupils through must be:

• meaningful - the pupil needs to have a sense of achievement

• successful - the pupil needs to be able to complete it

• logical - the path that the pupil takes through it needs to make sense

• usefully complete - the pupil must have an encounter with all of the actions, concepts and tools they need to become familiar with

It’s not easy being a teacher.

The Problem of Tutorials

In general, tutorials are the weakest part of documentation, the most misunderstood and the most difficult to do well. Most software projects have poor - or non-existent - tutorials.

In an ideal lesson, the teacher is present and interacts with and responds to the student. A written tutorial is a far-from-perfect substitute for this.

The sheer amount of work required to create and maintain tutorials is much more than that required for the other parts of documentation. It’s hard enough to put together a learning experience that meets all the standards described above; in many contexts the product itself evolves rapidly, meaning that all that work needs to be done again to ensure that the tutorial still performs its required functions.

Finally, you will find that no other part of your documentation is subject to revisions the way your tutorials are. You only have to change a reference or how-to guide if something in the product changes, and even then, usually only part of it needs to change. In the case of a tutorial you may come to the conclusion that the whole lesson should be completely rewritten, because you have thought of a better way produce a learning experience for the pupil.

You can easily find that writing and maintaining your tutorials occupies as much time and energy as the the other three parts put together.

The Language of Tutorials

In this tutorial, you will…

Describe what the learner will accomplish (note - not: “you will learn…”).

First, do x. Now, do y. Now that you have done y, do z.

No room for ambiguity or doubt.

We must always do x before we do y because… (see Explanation for more details).

Provide minimal explanation of actions in the most basic language possible. Link to more detailed explanation.

The output should look something like this…

Give your learner clear expectations.

Notice that… Remember that…

Give your learner plenty of clues to help confirm they are on the right track and orient themselves.

You have built a secure, three-layer hylomorphic stasis engine…

Describe (and admire, in a mild way) what your learner has accomplished (note - not: “you have learned…”)

How-To Guides   Top

Introduction to 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. (Docs)

How-to guides can be thought of as recipes, directions that guide the reader through the steps to achieve a specific end.

Examples could be: how to calibrate the radar array; how to use fixtures in pytest; how to configure reconnection back-off policies. On the other hand, how to build a web application is not - that’s not addressing a specific goal or problem, it’s a vastly open-ended sphere of skill.

How-to guides matter not just because users need to be able to accomplish things: the list of how-to guides in your documentation helps frame the picture of what your product can actually do. A rich list of how-to guides is an encouraging suggestion of a product’s capabilities.

If they’re well-written and address the right subjects, you’re likely to find that how-to guides are the most-read sections of your documentation.

Writing a Good How-To Guide

Describe a Sequence of Actions

Like a tutorial, a how-to guide contains a sequence of actions, that have an order. Unlike a tutorial, you don’t have to start at the beginning of the whole story and take your reader right to the end. Most likely, your user will also be in the middle of something - so you only need to provide a starting-point that they know how to reach, and a conclusion that actually answers a real question.

How-to guides should be reliable, but they don’t need to have the cast-iron repeatability of a tutorial.

Solve a Problem

The problem or task is the concern of a how-to guide: stick to that practical goal. Anything else that’s added - unnecessary explanation, for example - distracts both you and the user and dilutes the useful power of the guide.

Don’t Explain Concepts

An explanation doesn’t show you how to do something - so a how-to guide should not try to explain things. Explanation here will simply get in the way of the action. If explanations are important, link to them.

Be Flexible

A tutorial needs to be didactic in nature, but a how-to guide needs to be adaptable to real-world use-cases. A how-to guide that is useless for any purpose except exactly the narrow one you have addressed is rarely valuable.

Omit the Unnecessary

In how-to guides, practical usability is more helpful than completeness. Whereas a tutorial needs to be a complete, end-to-end guides, a how-to guide does not. It should start and end in some reasonable, meaningful place, and require the reader to join it up to their own work.

Pay Attention to Naming

Choose titles that say exactly what a how-to guide shows.

• good: How to integrate application performance monitoring

• bad: Integrating application performance monitoring (maybe the document is about how to decide whether you should, not about how to do it)

• very bad: Application performance monitoring (maybe it’s about how - but maybe it’s about whether, or even just an explanation of what it is)

Note that search engines appreciate good titles just as much as humans do.

The Language of How-To Guides

This guide shows you how to…

Describe clearly the problem or task that the guide shows the user how to solve.

If you want x, do y. To achieve w, do z.

Use conditional imperatives.

Refer to the x reference guide for a full list of options.

Don’t pollute your practical how-to guide with every possible thing the user might do related to x.

Reference   Top

An Introduction to Reference

Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented. (Docs)

The only purpose of a reference guide is to describe, as succinctly as possible, and in an orderly way. Whereas the content of tutorials and how-to guides are led by needs of the user, reference material is led by the product it describes.

In the case of software, reference guides describe the software itself - APIs, classes, functions and so on - and how to use them.

Your users need reference material because they need truth and certainty - firm platforms on which to stand while they work. Good technical reference is essential to provide users with the confidence to do their work.

Reference material should be austere and to the point. One hardly reads reference material; one consults it.

There should be no doubt or ambiguity in reference; it should be wholly authoritative.

Reference as Description

Reference material is like a map. A map tells you what you need to know about the territory, without having to go out and check the territory for yourself; a reference guide serves the same purpose for the product and its internal machinery.

In Reference Do Nothing but Describe

Technical reference has one job: to describe, and to do that clearly, accurately and comprehensively. Doing anything else - explaining, discussing, instructing, speculating - gets in the way of that job, and makes it harder for the reader to find the information they need.

It can be tempting to introduce instruction and explanation, simply because technical reference can seem too bare. Instead, link to how-to guides, explanation and introductory tutorials as appropriate.

Writing a Good Reference Guide

Be Consistent

Reference material benefits from consistency. Be consistent, in structure, language, terminology, tone. There are many opportunities in writing to delight your readers with your extensive vocabulary and command of multiple styles, but reference material is definitely not one of them.

Provide Examples

Examples are valuable ways of providing illustration that helps readers understand reference, without becoming distracted from the job of describing. For example, an example of usage of a command can be a succinct way of illustrating it and its context.

Be Accurate

These descriptions must be accurate and kept up-to-date. Any discrepancy between the machinery and your description of it will inevitably lead a user astray.

The Language of Reference Guides

X is an example of y. W needs to be initialised using z. This option does that.

State facts about the machinery and its behaviour.

Sub-commands are: a, b, c, d, e, f.

List commands, options, operations, features, flags, limitations, error messages, etc.

You must use a. You must not apply b unless c. Never d.

Provide warnings where appropriate.