Diátaxis

A lesson entails a relationship between a teacher and a pupil. In all learning of this kind, learning takes place as the pupil applies themself to tasks under the instructor’s guidance.

A lesson is a learning experience. In a learning experience, what matters is what the learner does and what happens. By contrast, the teacher’s explanations and recitations of fact are far less important.

A good lesson gives the learner confidence, by showing them that they can be successful in a certain skill or with a certain product.

A tutorial is a pedagogical problem.

It’s not an easy problem, but neither is it a mystery. The principles outlined below - repetition, action, small steps, results early and often, concreteness and so on - are not secrets, but they are not always well understood.

Still, there are straightforward, effective ways to address the problems of pedagogy in practice.

The first rule of teaching is simply: don’t try to teach. Your job, as a teacher, is to provide the learner with an experience that will allow them to learn. A teacher inevitably feels a kind of anxiety to impart knowledge and understanding, but if you give into it and try to teach by telling and explaining, you will jeopardise the learning experience.

Instead, allow learning to take place, and trust that it will. Give your learner things to do, through which they can learn. Only your pupil can learn. Sadly, however much you desire it, you will not be able to learn for your pupil. You cannot make them learn. All you can do is make it so they can learn.

We …

The first-person plural affirms the relationship between tutor and learner: you are not alone; we are in this together.

In this tutorial, we will …

Describe what the learner will accomplish.

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 …

Give your learner clear expectations.

Notice that … Remember that … Let’s check …

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.

Someone who has had the experience of teaching a child to cook will understand what matters in a tutorial, and just as importantly, the things that don’t matter at all.

It really doesn’t matter what the child makes, or how correctly they do it. The value of a lesson lies in what the child gains, not what they produce.

Success in a cooking lesson with a child is not the culinary outcome, or whether the child can now repeat the processes on their own. Success is when the child acquires the knowledge and skills you were hoping to impart.

It’s a crucial condition of this that the child discovers pleasure in the experience of being in the kitchen with you, and wants to return to it. Learning a skill is never a once and for all matter. Repetition is always required.

Meanwhile, the cooking lesson might be framed around the idea of learning how to prepare a particular dish, but what we actually need the child to learn might be things like: that we wash our hands before handling food; how to hold a knife; why the oil must be hot; what this utensil is called, how to time and measure things.

The child learns all this by working alongside you in the kitchen; in its own time, at its own pace, through the activities you do together, and not from the things you say or show.

With a young child, you will often find that the lesson suddenly has to end before you’d completed what you set out to do. This is normal and expected; children have short attention spans. But as long as the child managed to achieve something - however small - and enjoyed doing it, it will have laid down something in the construction of its technical expertise, that can be returned to and built upon next time.

How-to guides must be written from the perspective of the user, not of the machinery. A how-to guide represents something that someone needs to get done. It’s defined in other words by the needs of a user. Every how-to guide should answer to a human project, in other words. It should show what the human needs to do, with the tools at hand, to obtain the result they need.

This is in strong contrast to common pattern for how-to guides that often prevails, in which how-to guides are defined by operations that can be performed with a tool or system. The problem with this latter pattern is that it offers little value to the user; it is not addressed to any need the user has. Instead, it’s focused on the tool, on taking the machinery through its motions.

This is fundamentally a distinction of meaningfulness. Meaning is given by purpose and need. There is no purpose or need in the functionality of a machine. It is merely a series of causes and effects, inputs and outputs.

Consider:

• “To shut off the flow of water, turn the tap clockwise.”
• “To deploy the desired database configuration, select the appropriate options and press Deploy.”

The examples above look like examples of guidance, but they are not.

They represent mostly useless information that anyone with basic competence - anyone who is working in this domain - should be expected to know. Between them, standardised interfaces and generally-expected knowledge should make it quite clear what effect most actions will have.

Secondly, they are disconnected from purpose. What the user needs to know might be things like:

• how much water to run, and how vigorously to run it, for a certain purpose
• what database configuration options align with particular real-world needs

Tools appear in how-to guides as incidental bit-players, the means to the user’s end. Sometimes of course, a particular end is closely aligned with a particular tool or part of the system, and then you will find that a how-to guide indeed concentrates on that. Just as often, a how-to guide will cut across different tools or parts of a system, joining them up together in a series of activities defined by something a human being needs to get done. In either case, it is that project that defines what a how-to guide must cover.

How-to guides are wholly distinct from tutorials. They are often confused, but the user needs that they serve are quite different. Conflating them is at the root of many difficulties that afflict documentation. See The difference between a tutorial and how-to guide for a discussion of this distinction.

In another confusion, how-to guides are often construed merely as procedural guides. But solving a problem or accomplishing a task cannot always be reduced to a procedure. Real-world problems do not always offer themselves up to linear solutions. The sequences of action in a how-to guide sometimes need to fork and overlap, and they have multiple entry and exit-points. Often, a how-to guide will need the user to rely on their judgement in applying the guidance it can provide.

A how to-guide is concerned with work - a task or problem, with a practical goal. Maintain focus on that goal.

Anything else that’s added distracts both you and the user and dilutes the useful power of the guide. Typically, the temptations are to explain or to provide reference for completeness. Neither of these are part of guiding the user in their work. They get in the way of the action; if they’re important, link to them.

A how-to guide serves the work of the already-competent user, whom you can assume to know what they want to do, and to be able to follow your instructions correctly.

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.

Consider a recipe, an excellent model for a how-to guide. A recipe clearly defines what will be achieved by following it, and addresses a specific question (How do I make…? or What can I make with…?).

It’s not the responsibility of a recipe to teach you how to make something. A professional chef who has made exactly the same thing multiple times before may still follow a recipe - even if they created the recipe themselves - to ensure that they do it correctly.

Even following a recipe requires at least basic competence. Someone who has never cooked before should not be expected to follow a recipe with success, so a recipe is not a substitute for a cooking lesson.

Someone who expected to be provided with a recipe, and is given instead a cooking lesson, will be disappointed and annoyed. Similarly, while it’s interesting to read about the context or history of a particular dish, the one time you don’t want to be faced with that is while you are in the middle of trying to make it. A good recipe follows a well-established format, that excludes both teaching and discussion, and focuses only on how to make the dish concerned.

Reference material describes the machinery. It should be austere. One hardly reads reference material; one consults it.

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

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.

Although reference should not attempt to show how to perform tasks, it can and often needs to include a description of how something works or the correct way to use it.

Some reference material (such as API documentation) can be generated automatically by the software it describes, which is a powerful way of ensuring that it remains faithfully accurate to the code.

Django’s default logging configuration inherits Python’s defaults. It’s available as django.utils.log.DEFAULT_LOGGING and defined in django/utils/log.py

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.

You might check the information on a packet of food, in order to help you make a decision about what to do.

When you’re looking for information - relevant facts - you do not want to be confronted by opinions, speculation, instructions or interpretation.

You also expect that information to be presented in standard ways, so that you - when you need to know about something’s nutritional properties, how it should be stored, its ingredients, what health implications it might have - can find them quickly, and know you can rely on them.

So you expect to see for example: May contain traces of wheat. Or: Net weight: 1000g.

You will certainly not expect to find for example recipes or marketing claims mixed up with this information; that could be literally dangerous.

The way reference material is presented on food products is so important that it’s usually governed by law, and the same kind of seriousness should apply to all reference documentation.

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.

In 1984 Harold McGee published On food and cooking.

The book doesn’t teach how to cook anything. It doesn’t contain recipes (except as historical examples) and it isn’t a work of reference. Instead, it places food and cooking in the context of history, society, science and technology. It explains for example why we do what we do in the kitchen and how that has changed.

It’s clearly not a book we would read while cooking. We would read when we want to reflect on cooking. It illuminates the subject by taking multiple different perspectives on it, shining light from different angles.

After reading a book like On food and cooking, our understanding is changed. Our knowledge is richer and deeper. What we have learned may or may not be immediately applicable next time we are doing something in the kitchen, but it will change how we think about our craft, and will affect our practice.

The compass can be applied equally to user situations that need documentation, or to documentation itself that perhaps needs to be moved or improved. Like many good tools, it’s surprising banal.

To use the compass, just two questions need to be asked: action or cognition? acquisition or application?

And it yields the answer.

The compass is particularly effective when you think that you think you (or even the documentation in front of you) are doing one thing - but you are troubled by a sense of doubt, or by some difficulty in the work. The compass forces you to stop and reconsider.

Especially when you are trying to find your initial bearings, use the compass’s terms flexibly; don’t get fixated on the exact names.

• action: practical steps, doing
• cognition: theoretical or propositional knowledge, thinking
• acquisition: study
• application: work

And the questions themselves can also be used in different ways:

• Do I think I am writing for x or y?
• Is this writing in front of me engaged in x or y?
• Does the user need x or y?
• Do I want to x or y?

And try applying them close-up, at the level of sentences and words, or from a wider perspective, considering an entire document.

Diátaxis describes a complete picture of documentation. However the structure it proposes is not intended to be a plan, something you must complete in your documentation. It’s a guide, a map to help you check that you’re in the right place and going in the right directions.

The point of Diátaxis is to give you a way to think about and understand your documentation, so that you can make better sense of what it’s doing and what you’re trying to do with it. It provides tools that help assess it, identify where its problems lie, and judge what you can do to improve it.

Although structure is key to documentation, using Diátaxis means not spending energy trying to get its structure correct.

If you continue to follow the prompts that Diátaxis provides, eventually your documentation will assume the Diátaxis structure - but it will have assumed that shape because it has been improved. It’s not the other way round, that the structure must be imposed upon documentation to improve it.

In practice, this means that getting started with Diátaxis doesn’t require thinking about dividing up your documentation into the four sections, or writing out headings to put material under.

Instead, following the workflow described in the next two sections, make changes where you see opportunities for improvement according to Diátaxis principles, so that the documentation starts to take a certain shape. At a certain point, the changes you have made will appear to demand that you move material under a certain Diátaxis heading - and that is how your top-level structure will form. In other words, Diátaxis changes the structure of your documentation from the inside.

Diátaxis strongly prescribes a structure, but whatever the state of your existing documentation - even if it’s a complete mess by any standards - it’s always possible to improve it, iteratively.

It’s natural to want to complete large tranches of work before you publish them, so that you have something substantial to show each time. Avoid this temptation - every step in the right direction is worth publishing immediately.

Although Diátaxis is intended to provide a big picture of documentation, don’t try to work on the big picture. It’s both unnecessary and unhelpful. Diátaxis is designed to guide small steps; keep taking small steps to arrive where you want to go.

If you’re tidying up a huge mess, the temptation is to tear it all down and start again. Again, avoid it. As far as improving documentation in-line with Diátaxis goes, it isn’t necessary to seek out things to improve. Instead, the best way to apply Diátaxis is as follows:

Choose something - any piece of the documentation. If you don’t already have something that you know you want to put right, don’t go looking for outstanding problems. Just look at what you have right in front of you at that moment: the file you’re in, the last page you read - it doesn’t matter. If there isn’t one just choose something, literally at random.

Assess it. Next consider this thing critically. Preferably it’s a small thing, nothing bigger than a page - or better, even smaller, a paragraph or a sentence. Challenge it, according to the standards Diátaxis prescribes: What user need is represented by this? How well does it serve that need? What can be added, moved, removed or changed to serve that need better? Do its language and logic meet the requirements of this mode of documentation?

Decide what to do. Decide, based on your answers to those questions: 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, or at least commit the change. Don’t feel that you need to do anything else to make a worthy improvement.

And then go back to the beginning of the cycle.

Working like this helps reduce the stress of one of the most paralysing and troublesome aspects of the documentation-writer’s work: working out what to do. It keeps work flowing in the right direction, always towards the desired end, without having to expend energies on a plan.

There’s a strong urge to work in a cycle of planning and execution in order to work towards results. But it’s not the only way, and there are often better ways when working with documentation.

2.6.5.1. Well-formed organic growth

A good model for documentation is well-formed organic growth that adapts to external conditions. Organic growth takes place at the cellular level. The structure of the organism as a whole is guaranteed by the healthy development of cells, according to rules that are appropriate to each kind of cell. It’s not the other way round, that a structure is imposed on the organism from above or outside. Good structure develops from within.

It’s the same with documentation: by following the principles that Diátaxis provides, your documentation will attain a healthy structure, because its internal components themselves are well-formed - like a living organism, it will have built itself up from the inside-out, one cell at a time.

Diátaxis is based on the principle that documentation must serve the needs of its users. Knowing how to do that means understanding what the needs of users are.

The user whose needs Diátaxis serves is the practitioner in a domain of skill. A domain of skill is defined by a craft - the use of a tool or product is a craft. So is an entire discipline or profession. Using a programming language is a craft, as is flying a particular aircraft, or even being a pilot in general.

Understanding the needs of these users means in turn understanding the essential characteristics of craft or skill.

3.1.1.3. The map of the territory

This gives us two dimensions of skill, that we can lay out on a map - a map of the territory of craft:

This is a complete map. There are only two dimensions, and they don’t just cover the entire territory, they define it. This is why there are necessarily four quarters to it, and there could not be three, or five. It is not an arbitrary number.

It also shows us the qualities of craft that define each of them. When the idea that documentation must serve the needs of craft is applied to this map, it reveals in turn what documentation must be and do to fulfil those obligations - in four distinct ways.

The map of the territory of craft is what gives us the familiar Diátaxis map of documentation. The map is in effect an answer to the question: what must documentation do to align with these qualities of skill, and to what need is it oriented in each case?

We can see how the map of documentation addresses needs across those two dimensions, each need also defined by the characteristics of its quarter of the map.

The Diátaxis map of documentation is a memorable and approachable idea. But, a map is only reliable if it adequately describes a reality. Diátaxis is underpinned by a systematic description and analysis of generalised user needs.

This is why the tutorials, how-to guides, reference and explanation of Diátaxis are a complete enumeration of the types of documentation that serve practitioners in a craft. This is why there are four and only four types of documentation. There is simply no other territory to cover.

When documentation fails to attain a good structure, it’s rarely just a problem of structure (though it’s bad enough that it makes it harder to use and maintain). Architectural faults infect and undermine content too.

In the absence of a clear, generalised documentation architecture, documentation creators will often try to structure their work around features of a product.

This is rarely successful, even in a single instance. In a portfolio of documentation instances, the results are wild inconsistency. Much better is the adoption of a scheme that tries to provide an answer to the question: how to arrange documentation in general?

In fact any orderly attempt to organise documentation into clear content categories will help improve it (for authors as well as users), by providing lists of content types.

Even so, authors often find themselves needing to write particular documentation content that fails to fit well within the categories put forward by a scheme, or struggling to rewrite existing material. Often, there is a sense of arbitrariness about the structure that they find themselves working with - why this particular list of content types rather than another? And if another competing list is proposed, which to adopt?

A clear advantage of organising material this way is that it provides both clear expectations (to the reader) and guidance (to the author). It’s clear what the purpose of any particular piece of content is, it specifies how it should be written and it shows where it should be placed.

Each piece of content is of a kind that not only has one particular job to do, that job is also clearly distinguished from and contrasted with the other functions of documentation.

Most documentation systems and authors recognise at least some of these distinctions and try to observe them in practice.

However, there is a kind of natural affinity between each of the different forms of documentation and its neighbours on the map, and a natural tendency to blur the distinctions (that can be seen repeatedly in examples of documentation).

When these distinctions are allowed to blur, the different kinds of documentation bleed into each other. Writing style and content make their way into inappropriate places. It also causes structural problems, which make it even more difficult to maintain the discipline of appropriate writing.

In the worst case there is a complete or partial collapse of tutorials and how-to guides into each other, making it impossible to meet the needs served by either.

Diátaxis is intended to help documentation better serve users in their cycle of interaction with a product.

This phrase should not be understood too literally. It is not the case that a user must encounter the different kinds of documentation in the order tutorials > how-to guides > technical reference > explanation. In practice, an actual user may enter the documentation anywhere in search of guidance on some particular subject, and what they want to read will change from moment to moment as they use your documentation.

However, the idea of a cycle of documentation needs, that proceeds through different phases, is sound and corresponds to the way that people actually do become expert in a craft. There is a sense and meaning to this ordering.

• learning-oriented phase: We begin by learning, and learning a skill means diving straight in to do it - under the guidance of a teacher, if we’re lucky.
• goal-oriented phase: Next we want to put the skill to work.
• information-oriented phase: As soon as our work calls upon knowledge that we don’t already have in our head, it requires us to consult technical reference.
• explanation-oriented phase: Finally, away from the work, we reflect on our practice and knowledge to understand the whole.

And then it’s back to the beginning, perhaps for a new thing to grasp, or to penetrate deeper.

We need documentation to meet standards of accuracy, completeness, consistency, usefulness, precision and so on. We can call these aspects of its functional quality. Documentation that fails to meet any one of them is failing to perform one of its key functions.

These properties of functional quality are all independent of each other. Documentation can be accurate without being complete. It can be complete, but inaccurate and inconsistent. It can be accurate, complete, consistent and also useless.

Attaining functional quality means meeting high, objectively-measurable standards in multiple independent dimensions, consistently. It requires discipline and attention to detail, and high levels of technical skill.

To make it harder for the creator of documentation, any failure to meet all of these standards is readily apparent to the user.

There are other characteristics, that we can call deep quality.

Functional quality is not enough, or even satisfactory on its own as an ambition. True excellence in documentation implies characteristics of quality that are not included in accuracy, completeness and so on.

Think of characteristics such as:

• feeling good to use
• having flow
• fitting to human needs
• being beautiful
• anticipating the user

Unlike the characteristics of functional quality, they cannot be checked or measured, but they can still be clearly identified. When we encounter them, we usually (not always, because we need to be capable of it) recognise them.

They are characteristics of deep quality.

Aspects of deep quality seem to be genuinely distinct in kind from the characteristics of functional quality.

Documentation can meet all the demands of functional quality, and still fail to exhibit deep quality. There are many examples of documentation that is accurate and consistent (and even very useful) but which is also awkward and unpleasant to use.

It’s also noticeable that while characteristics of functional quality such as completeness and accuracy are independent of each other, those of deep quality are hard to disentangle. Having flow and anticipating the user are aspects of each other - they are interdependent. It’s hard to see how something could feel good to use without fitting to our needs.

Aspects of functional quality can be measured - literally, with numbers, in some cases (consider completeness). That’s clearly not possible with qualities such as having flow. Instead, such qualities can only be enquired into, interrogated. Instead of taking measurements, we must make judgements.

Functional quality is objective - it belongs to the world. Accuracy of documentation means the extent to which it conforms to the world it’s trying to describe. Deep quality can’t be ascertained by holding something up to the world. It’s subjective, which means that we can assess it only in the light of the needs of the subject of experience, the human.

And, deep quality is conditional upon functional quality. Documentation can be accurate and complete and consistent without being truly excellent - but it will never have deep quality without being accurate and complete and consistent. No user of documentation will experience it as beautiful, if it’s inaccurate, or enjoy the way it anticipates their needs if it’s inconsistent. The moment we run into such lapses the experience of documentation is tarnished.

Finally, all of the characteristics of functional quality appear to us, as documentation creators, as burdens and constraints. Each one of them represents a test or challenge we might fail. Or, even if we have met one now, we can never rest, because the next release or update means that we’ll have to check our work once again, against the thing that it’s documenting. Characteristics such as anticipating needs or flow, on the other hand, represent liberation, the work of creativity or taste. To attain functional quality in our work, we must conform to constraints; to attain deep quality we must invent.

Consider how we judge the quality of say, clothing. Clothes must have functional quality (they must keep us appropriately warm and dry, stand up to wear). These things are objectively measurable. You don’t really need to know much about clothes to assess how well they do those this. If water gets in, or the clothing falls apart - it lacks quality.

There are other characteristics of quality in clothing that can’t simply be measured objectively, and to recognise those characteristics, we need to have an understanding of clothing. The quality of materials or workmanship isn’t always immediately obvious. Being able to judge that an item of clothing hangs well, moves well or has been expertly shaped requires developing at least a basic eye for those things. And these are its characteristics of deep quality.

But: even someone who can’t recognise, or fails to understand, those characteristics - who cannot say what they are - can still recognise very well that the clothing is excellent, because they find it that it feels good to wear, because it’s such that they want to wear it. No expertise is required to realise that clothing does or doesn’t feel comfortable as you move in it, that it fits and moves with you well. Your body knows it.

And it’s the same in documentation. Perhaps you need to be a connoisseur to recognise what it is that makes some documentation excellent, but that’s not necessary to be able to realise that it is excellent. Good documentation feels good; you feel pleasure and satisfaction when you use it - it feels like it fits and moves with you.

The users of our documentation may or may not have the understanding to say why it’s good, or where its quality lapses. They might recognise only the more obvious aspects of functional quality in it, mistaking those for its deeper excellence. That doesn’t matter - it will feel good, or not, and that’s what is important.

But we, as its creators, need a clear and effective understanding of what makes documentation good. We need to develop our sense of it so that we recognise what is good about it, as well as that it is good. And we need to develop an understanding of how people will feel when they’re using it.

Producing work of deep quality depends on our ability to do this.

Functional quality’s obligations are met through conscientious observance of the demands of the craft of documentation. They require solid skill and knowledge of the technical domain, the ability to gather up a complete terrain into a single, coherent, consistent map of it.

Diátaxis cannot address functional quality in documentation. It is concerned only with certain aspects of deep quality, some more than others - though if all the aspects of deep quality are tangled up in each other, then it affects all of them.

In important respects, tutorials and how-to guides are indeed similar. They are both practical guides: they contain directions for the user to follow. They’re not there to explain or convey information. They exist to guide the user in what to do rather than what there is to know or understand.

They both set out steps for the reader to follow, and they both promise that if the reader follows those steps, they’ll arrive at a successful conclusion. Neither of them make much sense except for the user who has their hands on the machinery, ready to do things. They both describe ordered sequences of actions. You can’t expect success unless you perform the actions in the right order.

They are closely related, and like many close relations, can be mistaken for one another at first glance.

Diátaxis insists that what matters in documentation is the needs of the user, and it’s by paying attention to this that we can correctly distinguish between tutorials and how-to guides.

Sometimes the user is at study, and sometimes the user is at work. Documentation has to serve both those needs.

A tutorial serves the needs of the user who is at study. Its obligation is to provide a successful learning experience. A how-to guide serves the needs of the user who is at work. Its obligation is to help the user accomplish a task. These are completely different needs and obligations, and they are why the distinction between tutorials and how-to guides matters: tutorials are learning-oriented, and how-to guides are task-oriented.

We can consider this from the perspective of an actual example. Let’s say you’re in medicine: a doctor, someone who needs to acquire and apply the practical, clinical skills of their craft.

As a doctor, sometimes you will be in work situations, applying your skills, and sometimes you will be in study situations, acquiring skills (all good doctors, even those with long careers behind them, continue to study to improve their skills).

3.4.3.1. At study

Early on in your training, you’ll learn how to suture a wound. You’ll start in the lab with your fellow students, at benches with small skin pads in front of you (skin pads are blocks of synthetic material in various layers that represent the epidermis, fat and other tissues. They have a similar hardness and texture to human flesh, and behave somewhat similarly when they’re cut and stitched). You’ll be provided with exactly what you need - gloves, scalpel, needle, thread and so on - and step-by-step you’ll be shown what to do, and what will happen when you do it.

And then it’s your turn. You will pick up the scalpel and tentatively draw it across the top of the pad, and make an ineffectual incision into the top layer (maybe a teaching assistant will tease you, asking what this poor pad has done, that it deserves such a nasty scratch). Your neighbour will look dismayed at their own attempt, a ragged cut of wildly uneven depths that looks like something from a knife-fight.

After a few attempts, with feedback and correction from the tutor, you’ll have made a more or less clean cut that mostly goes through the fat layer without cutting into the muscle beneath. Triumph!

But now you’re being asked to stitch it back up again! You’ll watch the tutor demonstrate deftly and precisely, closing the wound in the pad with a few neat, even stitches. You, on the other hand, will fumble with the thread. You will hold things in the wrong hand and the wrong way round and put them down in the wrong places. You will drop the needle. The thread will fall out. You will be told off for failing to maintain sterility.

Eventually, you’ll actually get to stitch the wound. You will puncture the skin in the wrong places and tear the edges of the cut. Your final result will be an ugly scene of stretched and puckered skin and crude, untidy stitches. The teaching assistants will have some critical things to say even about parts of it that you thought you’d got right.

But, you will have stitched your first wound. And you will come back to this lesson again and again, and bit by bit your fumbling will turn into confident practice. You will have acquired basic competence. You will have learned by doing.

This is a tutorial. It’s a lesson, safely in the hands of an instructor, a teacher who looks after the interests of a pupil.

3.4.3.2. At work

Now, let’s think about the doctor at work. As a doctor at work, you are already competent. You have learned and refined clinical skills such as suturing, as well as many others, and you’re able to put them together on a daily basis to apply them to medical situations in the real world.

Consider a standard appendectomy. A clinical manual will list the equipment and personnel required in the theatre. It will show how to station the members of the team, and how to lay out the required tools, stands and monitors. It will proceed step-by-step through the actions the team will need to follow, ending with the formal handover to the post-operative team.

The manual will show what incisions need to be made where, but they will depend on whether you’re performing an open or a laparoscopic procedure, whether you have pre-operative imaging to rely on or not, and so on. It will include special steps or checks to be made in the case of an infant or juvenile patient, or when converting to an open appendectomy mid-procedure. Many of the steps will be of the form if this, then that.

Having a manual helps ensure that all the steps are done in the right order and none are omitted. As a team, you’ll check through details of a procedure to remind yourselves of key steps; sometimes you’ll refer to it during the procedure itself.

Even for routine surgical operations, clinical manuals contain lists of steps and checks. These manuals are how-to guides. They are not there to teach you - you already have your skills. You already know these processes. They are there to guide you safely in your clinical practice to accomplish a particular task - they serve your work.

The distinction between a lesson in medical school and a clinical manual is the distinction between a tutorial and a how-to guide.

None of these distinctions are arbitrary. They all emerge from the distinction between study and work, which we understand as a key distinction in making sense of what the user of documentation needs.

A common but understandable conflation is to see the difference between tutorials and how-to guides as being the difference between the basic and the advanced.

After all, tutorials are for learners, while how-to guides are for already-skilled practitioners. Tutorials must cover the basics, while how-to guides have to deal with complexities that learners should not have to face.

However, there’s more to the story. Consider a clinical procedure manual: it could be a manual for a basic routine procedure, of very low complexity. It could describe steps for mundane matters such as correct completion of paperwork or disposal of particular materials. How-to guides can, do and often should cover basic procedures.

At the same time, even as a qualified doctor, you will find yourself back in training situations. Some of them may be very advanced and specialised, requiring a high level of skill and expertise already.

Let’s say you’re an anaesthetist of many years’ experience, who attends a course: “Difficult neonatal intubations”. The practical part of the course will be a learning experience: a lesson, safely in the hands of the instructors, that will have you performing particular exercises to develop your skills - just as it was when years earlier, you were learning to suture your first wound.

The complexity is wholly different though, and so is the baseline of skills required even to participate in the learning experience. But, it’s of the same form, and serves the same kind of need, as that much earlier lesson.

It’s the same in software documentation: a tutorial can present something complex or advanced. And, a how-to guide can cover something that’s basic or well-known. The difference between the two lies in the need they serve: the user’s study, or their work.

Understanding these distinctions, and the reason for upholding them, is crucial to creating successful documentation. A clinical manual that conflated education with practice, that tried to teach while at the same time providing a guide to a real-world procedure would be a literally deadly document. It would kill people.

In disciplines such as software documentation, we get away with a great deal, because our conflations and mistakes rarely kill anyone. However, we can cause a great deal of low-level inconvenience and unhappiness to our users, and we add to it, every single time we publish a tutorial or how-to guide that doesn’t understand whether its purpose is to help the user in their study - the acquisition of skills - or in their work - the application of skills.

What’s more, we hurt ourselves too. Users don’t have to use our product. If our documentation doesn’t bring them to success - if it doesn’t meet the needs that they have at a particular stage in their cycle of interaction with our product - they will find something else that does, if they can.

The conflation of tutorials and how-to guides is by no means the only one made between different kinds of documentation, but it’s one of the easiest to make. It’s also a particularly harmful one, because it risks getting in the way of those newcomers whom we hope to turn into committed users. For the sake of those users, and of our own product, getting the distinction right is a key to success.

Mostly it’s fairly straightforward to recognise whether you’re dealing with one or the other. Reference, as a form of writing, is well understood; it’s used in distinctions we make about writing from an early age.

In addition, examples of writing are themselves often clearly one or the other. A tidal chart, with its tables of figures, is clearly reference material. An article that explains why there are tides and how they behave is self-evidently explanation.

There are good rules of thumb:

• If it’s boring and unmemorable it’s probably reference.
• Lists of things (such as classes or methods or attributes), and tables of information, will generally turn out to belong in reference.
• On the other hand if you can imagine reading something in the bath, probably, it’s explanation (even if really there is no accounting for what people might read in the bath).

Imagine asking a friend, while out for a walk or over a drink, Can you tell me more about <topic>? - the answer or discussion that follows is most likely going to be an explanation of it.

The real test, though, if we’re in doubt about whether something is supposed to be reference or explanation is: is this something someone would turn to while working, that is, while actually getting something done, executing a task? Or is it something they’d need once they have stepped away from the work, and want to think about it?

These are two very fundamentally different needs of the reader, that reflect how, at that moment, the reader stands in relation to the craft in question, in a relationship of work or study.

Reference is what a user needs in order help apply knowledge and skill, while they are working.

Explanation is what someone will turn to to help them acquire knowledge and skill - “study”.

Understanding those two relationships and responding to the needs in them is the key to creating effective reference and explanation.

The application of Diátaxis to most documentation is fairly straightforward. The product that defines the domain of concern has clear boundaries, and it’s possible to come up with an arrangement of documentation contents that looks - for example - like this:

Home                      <- landing page
    Tutorial              <- landing page
	Part 1
	Part 2
	Part 3
    How-to guides         <- landing page
	Install
	Deploy
	Scale
    Reference             <- landing page
	Command-line tool
	Available endpoints
	API
    Explanation           <- landing page
	Best practice recommendations
	Security overview
	Performance

In each case, a landing page contains an overview of the contents within. The tutorial for example describes what the tutorial has to offer, providing context for it.

Home                      <- landing page
    Tutorial              <- landing page
	Part 1
	Part 2
	Part 3
    How-to guides         <- landing page
+++++++++++++++++++++++++++++++++++++++++
	Install           <- landing page
	    Local installation
	    Docker
	    Virtual machine
	    Linux container
+++++++++++++++++++++++++++++++++++++++++
	Deploy
	Scale
    Reference             <- landing page
	Command-line tool
	Available endpoints
	API
    Explanation           <- landing page
	Best practice recommendations
	Security overview
	Performance

Contents pages - typically a home page and any landing pages - provide an overview of the material they encompass.

There is an art to creating a good contents page. The experience they give the users deserves careful consideration.

How to guides
=============

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Installation guides
-------------------

Pellentesque malesuada, ipsum ac mollis pellentesque, risus
nunc ornare odio, et imperdiet dui mi et dui. Phasellus vel
porta turpis. In feugiat ultricies ipsum.

* Local installation       |
* Docker                   |  links to
* Virtual machines         |  the guides
* Linux containers         |

Deployment and scaling
-----------------------

Morbi sed scelerisque ligula. In dictum lacus quis felis
facilisisvulputate. Quisque lacinia condimentum ipsum
laoreet tempus.

* Deploy an instance       |  links to
* Scale your application   |  the guides

A more difficult problem is when the structure outlined by Diátaxis meets another structure - often, a structure of topic areas within the documentation, or when documentation encounters very different user-types.

For example we might have a product that is used on land, sea and air, and though the same product, is used quite differently in each case. And it could be that a user who uses it on land is very unlikely to use it at sea.

Or, the product documentation addresses the needs of:

• users
• developers who build other products around it
• the contributors who help maintain it.

The same product, but very different concerns.

A final example: a product that can be deployed on different public clouds, with each public cloud presenting quite different workflows, commands, APIs, GUIs, constraints and so on. Even though it’s the same product, as far as the users in each case are concerned, what they need to know and do is very different - what they need is documentation not for product, but

• product-on-public-cloud-one
• product-on-public-cloud-two
• and so on…

So, we could decide on an overall structure that does this:

tutorial
    for users on land
	[...]
    for users at sea
	[...]
    for users in the air
	[...]
[and then so on for how-to guides, reference and explanation]

or maybe instead this:

for users on land
    tutorial
	[...]
    how-to guides
	[...]
    reference
	[...]
    explanation
	[...]
for users at sea
    [tutorial, how-to, reference, explanation sections]
for users in the air
    [tutorial, how-to, reference, explanation sections]

Which is better? There seems to be a lot of repetition in either cases. What about the material that can be shared between land, sea and air?

Diátaxis can be neatly represented in a diagram - but it is not the same as that diagram.

It should be understood as an approach, a way of working with documentation, that identifies four different needs and uses them to author and structure documentation effectively.

This will tend towards a clear, explicit, structural division into the four categories - but that is a typical outcome of the good practice, not its end.

Diátaxis is underpinned by attention to user needs, and once again it’s that concern that must direct us.

What we must document is the product as it is for the user, the product as it is in their hands and minds. (Sadly for the creators of products, how they conceive them is much less relevant.)

Is the product on land, sea and air effectively three different products, perhaps for three different users?

In that case, let that be the starting point for thinking about it.

If the documentation needs to meet the needs of users, developers and contributors, how do they see the product? Should we assume that a developer who incorporates it into other products will typically need a good understanding of how it’s used, and that a contributor needs to know what a developer knows too?

Then perhaps it makes sense to be freer with the structure, in some parts (say, the tutorial) allowing the developer-facing content to follow on from the user-facing material, while completely separating the contributors’ how-to guides from both.

And so on. If the structure is not the simple, uncomplicated structure we began with, that’s not a problem - as long as there is arrangement according to Diátaxis principles, that documentation does not muddle up its different forms and purposes.