Diataxis

Diátaxis Documentation Framework

Apply the Diátaxis systematic framework to structure and write documentation.

The Four Documentation Types

Diátaxis identifies exactly four types, defined by two axes:

1. Tutorials — learning-oriented

Write tutorials as lessons. Take the learner by the hand through a practical experience where they acquire skills by doing.

• Use first-person plural ("We will...")
• Show where they're going up front
• Deliver visible results early and often
• Ruthlessly minimize explanation — link to it instead
• Focus on the concrete, ignore options and alternatives
• Aspire to perfect reliability

Load `references/tutorials.md` for full guidance.

2. How-to guides — goal-oriented

Write how-to guides as practical directions for an already-competent user to achieve a specific real-world goal.

• Name clearly: "How to [achieve X]"
• Use conditional imperatives ("If you want x, do y")
• Assume competence — don't teach
• Omit the unnecessary; practical usability > completeness
• Allow flexibility with alternatives

Load `references/how-to-guides.md` for full guidance.

3. Reference — information-oriented

Write reference as technical description of the machinery. Keep it austere, authoritative, consulted not read.

• Describe and only describe — neutral tone
• Adopt standard, consistent patterns
• Mirror the structure of the product
• Provide examples to illustrate, not explain

Load `references/reference.md` for full guidance.

4. Explanation — understanding-oriented

Write explanation as discursive treatment that deepens understanding. Answer "Can you tell me about...?"

• Make connections to related topics
• Provide context: why things are so
• Talk about the subject (title: "About X")
• Admit opinion and perspective
• Keep closely bounded — don't absorb other types

Load `references/explanation.md` for full guidance.

The Compass — When In Doubt

Ask two questions to classify content:

1. Action or cognition? Is this about doing, or thinking? 2. Acquisition or application? Is this for learning, or for working?

The intersection tells you which type you're writing. Load references/compass.md for detailed decision guidance.

How To Apply

1. Classify the content — use the compass questions above. 2. Check for type mixing — does this piece try to do two things at once? 3. Separate mixed content — pull explanation out of tutorials, pull instructions out of reference. 4. Apply the type's principles — follow the bullet points for that type above. 5. Link between types — don't embed, cross-reference instead.

Do NOT create empty four-section structures and try to fill them. Let structure emerge from content.

Example

User asks: "Write a getting-started guide for our CLI tool."

1. Classify: "Getting started" = the user is learning, by doing → Tutorial. 2. Check: Not a how-to guide — the user isn't solving a specific problem, they're acquiring familiarity. 3. Apply tutorial principles:

• Open with what they'll build: "In this tutorial, we will install the CLI and deploy a sample app."
• Lead through concrete steps with visible results at each stage.
• Minimize explanation: "We use --verbose for more output" not a paragraph on logging levels.
• Link to reference for flag details, link to explanation for architecture.

4. Result: A focused lesson, not a feature tour disguised as a tutorial.

Common Mistakes

Critical Rules

• Never mix types. Each type has its own purpose, tone, and form.
• The user's mode matters. Study vs. work is the fundamental distinction. Tutorials and explanation serve study. How-to guides and reference serve work.
• Link between types rather than embedding one inside another.

Deep Dives

Load reference files on demand for detailed guidance:

diataxis

An agent skill for writing and organizing documentation using the Diátaxis framework.

The SKILL.md provides the core framework. Detailed guidance for each type lives in references/, downloaded from diataxis.fr and converted to markdown for use as agent context.

Attribution & License

Reference content derived from the Diátaxis documentation framework by Daniele Procida, licensed under CC BY-SA 4.0. To cite Diátaxis, refer to diataxis.fr. Citation metadata is available at the source repository.

Applying Diátaxis

Source: https://diataxis.fr/application/

The pages in this section are concerned with putting Diátaxis into practice.

Diátaxis is primarily intended as a pragmatic approach for people working on documentation. Most of the key principles required to put it into practice successfully can be grasped intuitively.

Don't wait to understand Diátaxis before you start trying to put it into practice. Not only do you not need to understand it all to make use of it, you will not understand it until you have started using it (this itself is a Diátaxis principle).

As soon as you feel you have picked up an idea that seems worth applying to your work, try applying it. Come back here when you need more clarity or reassurance. Iterate between your work and reflecting on your work.

---

In this section

At the core of Diátaxis are the four different kinds of documentation it identifies. If you're encountering Diátaxis for the first time, start with these pages.

• Tutorials - learning-oriented experiences
• How-to guides - goal-oriented directions
• Reference - information-oriented technical description
• Explanation - understanding-oriented discussion

Diátaxis prescribes principles that guide action. These translate into particular ways of working, with implications for documentation process and execution. Once you've made your first start, the tools and methods outlined here will help smooth your way.

• The compass - a simple tool for direction-finding
• Workflow in Diátaxis

Colophon

Source: https://diataxis.fr/colophon/

Diátaxis is the work of Daniele Procida.

It has been developed over a number of years, and continues to be elaborated and explored.

Origins and development

An earlier presentation of some of these ideas was created while working at Divio between 2014-2021.

The original context for the Diátaxis approach was limited to software product documentation.

In 2021 Daniele was awarded a Fellowship of the Software Sustainability Institute, to explore its application in scientific research contexts. More recently the application has been explored in internal corporate documentation, organisational management and education, and also its application at scale. This work is on-going.

Other people have corresponded to share their experience of applying Diátaxis to note-taking systems and even as part of a systematic approach to household management.

Citation and contribution

To cite Diátaxis, refer to diataxis.fr.

The Git repository for the source material contains a citation file, CITATION.cff, at the GitHub repository.

Website

The diataxis.fr website is built with Sphinx and hosted on Read the Docs, using a modified version of Pradyun Gedam's Furo theme.

Community

• Slack: _#diataxis_ channel on the Write the Docs Slack group
• GitHub Discussions: https://github.com/evildmp/diataxis-documentation-framework/discussions
• Issues: https://github.com/evildmp/diataxis-documentation-framework/issues

The compass

Source: https://diataxis.fr/compass/

The Diátaxis compass is a practical tool for categorizing and improving documentation. Rather than relying solely on intuition, which can be misleading, authors can use this decision framework to determine what type of documentation is needed or how to improve existing content.

Core Concept

The compass operates as a decision tree with two fundamental questions:

1. Action or Cognition? (practical doing vs. theoretical thinking) 2. Acquisition or Application? (learning new skills vs. using existing ones)

These four combinations yield the four documentation types:

Practical Application

The compass is particularly effective when you think that you (or even the documentation in front of you) are doing one thing - but you are troubled by a sense of doubt.

Authors should use the compass's terminology flexibly, understanding that:

• Action means practical steps and doing
• Cognition means theoretical knowledge and thinking
• Acquisition refers to study
• Application refers to work

Using the compass

When in doubt about what type of documentation you're writing or should be writing, ask:

1. Am I describing action or cognition? If action, you're in the practical half (tutorials/how-to). If cognition, you're in the theory half (reference/explanation). 2. Is this for acquisition or application? If acquisition (study), you're writing a tutorial or explanation. If application (work), you're writing a how-to guide or reference.

The questions can be applied at various scales — from individual sentences to entire documents — making this a versatile tool for documentation assessment and improvement.

When to use it

Use the compass when:

• You're unsure what type of documentation to write
• Existing documentation feels wrong or mixed up
• You want to verify that content belongs where it is
• A piece of documentation is trying to do too many things at once

Diátaxis in complex hierarchies

Source: https://diataxis.fr/complex-hierarchies/

Structure of Documentation Content

Diátaxis can organize documentation hierarchically, starting with a home page and branching into four main categories: tutorials, how-to guides, reference materials, and explanations. Each section typically has its own landing page that provides context.

Additional hierarchy layers can be added when needed. For instance, installation guides might be subdivided into separate approaches like local installation, Docker, virtual machines, and Linux containers.

Contents Pages

Landing pages and home pages serve as overviews of their encompassed material. The design of these pages significantly affects user experience.

Managing List Length

"Seven items seems to be a comfortable general limit." Lists exceeding this threshold become difficult to scan unless they follow natural ordering (numerical or alphabetical). When tables of contents grow longer, breaking them into smaller groupings improves readability.

The guiding principle remains user experience. "As always, what matters most is the experience of the reader."

Effective Landing Page Design

"The content of a landing page itself should read like an overview." Rather than merely listing links, landing pages should introduce their content through headings and contextual text snippets. This approach treats documentation as authored for human readers rather than as a structural scheme to be filled.

Two-Dimensional Problems

Documentation complexity increases when Diátaxis intersects with other organizing structures — such as different user types or deployment platforms. A product used in different contexts (land, sea, air) or by different audiences (users, developers, contributors) presents organizational challenges.

Two potential structures emerge:

1. Group by use case first, then apply Diátaxis within each group 2. Apply Diátaxis first, then subdivide each category by use case

Both approaches involve repetition and raise questions about shared content.

Understanding the Core Issue

"Diátaxis is not a scheme into which documentation must be placed — four boxes." Rather, it identifies four documentation types around which to structure content. The framework itself doesn't prescribe exactly four hierarchical divisions.

Diátaxis as an Approach

Diátaxis functions as a working methodology identifying user needs, not merely as a diagram or structural template. Following these principles typically produces clear divisions into four categories, but this organizational outcome serves the approach rather than defining it.

User-First Thinking

"Diátaxis is underpinned by attention to user needs," guiding structural decisions. Documentation should reflect how users perceive and interact with products, not how creators conceive them.

Determining whether a product serves fundamentally different users should shape documentation organization. If users, developers, and contributors need different knowledge levels, perhaps tutorial content could flow from user-facing to developer-facing material, while separating contributor guides entirely.

Embracing Complex Structures When Necessary

"Documentation should be as complex as it needs to be." Complex structures remain navigable when they follow logical patterns matching user needs. The goal isn't simplicity for its own sake but rather clarity and coherence serving the people reading the documentation.

Explanation

Source: https://diataxis.fr/explanation/

Explanation is a discursive treatment of a subject, that permits _reflection_. Explanation is understanding-oriented.

---

Explanation deepens and broadens the reader's understanding of a subject. It brings clarity, light and context.

The concept of _reflection_ is important. Reflection occurs _after_ something else, and depends on something else, yet at the same time brings something new - shines a new light - on the subject matter.

The perspective of explanation is higher and wider than that of the other three types. It does not take the user's eye-level view, as in a how-to guide, or a close-up view of the machinery, like reference material. Its scope in each case is a topic - "an area of knowledge", that somehow has to be bounded in a reasonable, meaningful way.

For the user, explanation joins things together. It's an answer to the question: _Can you tell me about...?_

It's documentation that it makes sense to read while away from the product itself (one could say, explanation is the only kind of documentation that it might make sense to read in the bath).

---

The value and place of explanation

Explanation and understanding

Explanation is characterised by its distance from the active concerns of the practitioner. It doesn't have direct implications for what they do, or for their work. This means that it's sometimes seen as being of lesser importance. That's a mistake; it may be less _urgent_ than the other three, but it's no less _important_. It's not a luxury. No practitioner of a craft can afford to be without an understanding of that craft, and needs the explanatory material that will help weave it together.

The word _explanation_ - and its cognates in other languages - refer to _unfolding_, the revelation of what is hidden in the folds. So explanation brings to the light things that were implicit or obscured.

Similarly, words that mean _understanding_ share roots in words meaning to hold or grasp (as in _comprehend_). That's an important part of understanding, to be able to hold something or be in possession of it. Understanding seals together the other components of our mastery of a craft, and makes it safely our own.

Understanding doesn't _come from_ explanation, but explanation is required to form that web that helps hold everything together. Without it, the practitioner's knowledge of their craft is loose and fragmented and fragile, and their exercise of it is _anxious_.

Explanation and its boundaries

Quite often explanation is not explicitly recognised in documentation; and the idea that things need to be explained is often only faintly expressed. Instead, explanation tends to be scattered in small parcels 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.

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_.

Admit opinion and perspective

Opinion might seem like a funny thing to introduce into documentation. The fact is that all human activity and knowledge is invested within opinion, with beliefs and thoughts. The reality of any human creation is rich with opinion, and that needs to be part of any understanding of it.

Similarly, any understanding comes from a perspective, a particular stand-point - which means that other perspectives and stand-points exist. Explanation can and must consider alternatives, counter-examples or multiple different approaches to the same question.

In explanation, 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_.

Keep explanation closely bounded

One risk of explanation is that it tends to absorb other things. The writer, intent on covering the topic, feels the urge to include instruction or technical description related to it. But documentation already has other places for these, and allowing them to creep in interferes with the explanation itself, and removes them from view in the correct place.

---

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.

---

Analogy from food and cooking

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_.

Foundations

Source: https://diataxis.fr/foundations/

Diátaxis is successful because it _works_ - both users and creators have a better experience of documentation as a result. It makes sense and it feels right.

However, that's not enough to be confident in Diátaxis as a theory of documentation. As a theory, it needs to show _why_ it works. It needs to show that there is actually some reason why there are exactly four kinds of documentation, not three or five. It needs to demonstrate rigorous thinking and analysis, and that it stands on a sound theoretical foundation.

Otherwise, it will be just another useful heuristic approach, and the strongest claim we can make for it is that "it seems to work quite well".

Two dimensions of craft

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.

Action/cognition

A skill or craft or practice contains both action (practical knowledge, knowing _how_, what we do) and cognition (theoretical knowledge, knowing _that_, what we think). The two are completely bound up with each other, but they are counterparts, wholly distinct from each other, two different aspects of the same thing.

Acquisition/application

Similarly, the relationship of a practitioner with their practice is that it is something that needs to be both acquired, and applied. Being "at work" (concerned with applying the skill and knowledge of their craft) and being "at study" (concerned with acquiring them) are once again counterparts, distinct but bound up with each other.

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.

Serving needs

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?

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.

How-to guides

Source: https://diataxis.fr/how-to-guides/

A how-to guide is a response to a question that only a user with some experience could even formulate. How-to guides are goal-oriented.

---

A how-to guide addresses a real-world goal or problem, by providing practical directions to help the user who is already competent enough to formulate the goal or understand the problem.

In how-to guides, the user has work to do. The user is at work, not at study.

How-to guides serve the user's _application_ of skill and knowledge - their work. Its purpose is to help the user get something done.

---

Core Principles

User-Centered Focus

The guides must address real-world problems from the user's perspective, not the tool's capabilities. "Tools appear in how-to guides as incidental bit-players, the means to the user's end." This distinction separates meaningful guidance from mere mechanical instructions.

Practical Over Complete

Guides should omit unnecessary information. "Practical usability is more helpful than completeness," allowing readers to integrate instructions into their own workflows rather than following rigid procedures.

Logical Sequencing

Steps should follow a natural order reflecting how users think and work. Consider both temporal requirements (step B depends on step A) and cognitive flow—how information connects meaningfully in a user's mind.

Clear Naming

Titles must state exactly what the guide demonstrates. Prefer "How to integrate application performance monitoring" over vague alternatives that leave the guide's purpose ambiguous.

Provide a set of directions that address a specific goal or problem

A how-to guide must address a specific question or problem. Don't try to make it more comprehensive than it needs to be.

Don't explain concepts

A how-to guide is not the place for explanation. If explanation is important, link to it. This keeps the guide focused on what the user needs to do.

Allow for some flexibility

A how-to guide should be adaptable. The user may need to apply it in different contexts or with variations. Where possible, present alternatives: "If you are using x, do a; if you prefer y, do b instead."

Omit the unnecessary

Practical usability is more helpful than completeness. How-to guides should be efficient and to the point.

---

The language of how-to guides

How to integrate application performance monitoring - Name guides clearly, starting with "How to..."

If you want x, do y. To achieve a, do b. - Conditional imperatives.

Refer to the x reference guide for a full list of options. - Don't pollute with reference material. Link to it.

---

Applied to food and cooking

Think of a recipe as a how-to guide. A recipe tells an already-competent cook how to make a particular dish. It's not there to teach you how to cook. It assumes you can already handle basic techniques. A recipe addresses a specific goal: producing a specific dish. It contains a set of steps, and it might offer some variations or alternatives ("you can substitute...").

A recipe is reliable because it solves a specific problem, and it does so in a way that respects the user's existing competence.

Workflow

Source: https://diataxis.fr/how-to-use-diataxis/

Diátaxis functions as both a documentation content framework and a methodology for documentation work itself. Rather than serving as a rigid implementation plan, it operates as a navigational guide helping documentation teams understand their work and identify improvement opportunities.

Core Principles

Structure Emerges from Improvement

The framework explicitly advises against pre-creating empty structural divisions. Instead, "Diátaxis changes the structure of your documentation from the inside" through incremental improvements that naturally coalesce into the four-part model (tutorials, how-to guides, reference, and explanation).

Iterative Small Steps

The methodology emphasizes working incrementally rather than attempting comprehensive overhauls. "Don't try to work on the big picture" — instead, publish improvements as you make them, even if individually modest.

The Four-Step Workflow

The recommended approach involves:

1. Selecting any documentation piece, however small 2. Assessing it against Diátaxis principles 3. Identifying one beneficial action 4. Completing and publishing that single change

Then repeating the cycle.

Organic Growth Model

Documentation should develop "like a living organism...built itself up from the inside-out, one cell at a time." The framework distinguishes between "finished" and "complete" — documentation is never truly finished but should always be functionally complete and useful at its current developmental stage.

This approach prioritizes responsive, adaptive work over planning-intensive processes, reducing the paralysis that often accompanies documentation projects.

Don't try to work on the big picture

Don't try to reorganize all your documentation at once. Don't create a grand plan. Instead:

• Pick something small
• Make it better
• Publish the improvement
• Repeat

Don't create empty structures

Don't create empty "Tutorials", "How-to", "Reference", "Explanation" sections and try to fill them. Let the structure emerge from the content as you improve it piece by piece.

The cycle of improvement

1. Look at existing documentation - Pick any piece 2. Assess it - What kind of documentation is it? What kind should it be? 3. Identify one action - What's one thing that would make it better? 4. Do it - Make the change and publish it 5. Repeat - Go back to step 1

Diátaxis

Source: https://diataxis.fr/

Diátaxis is a systematic approach to technical documentation authoring that addresses user needs through four distinct documentation types: tutorials, how-to guides, technical reference, and explanation. These forms are organized systematically to match how people actually use documentation.

Core Purpose

The framework addresses three fundamental documentation challenges:

• Content: What should be written
• Style: How it should be written
• Architecture: How it should be organized

Key Benefits

Beyond helping documentation users, Diátaxis offers value to creators and maintainers through lightweight principles that are straightforward to implement without imposing technical constraints.

Site Structure

Applying Diátaxis

• Start here - Diátaxis in five minutes
• Applying Diátaxis - Putting Diátaxis into practice
• Tutorials - Learning-oriented experiences
• How-to guides - Goal-oriented directions
• Reference - Information-oriented technical description
• Explanation - Understanding-oriented discussion
• The compass - A simple tool for direction-finding
• Workflow - How to use Diátaxis

Understanding Diátaxis

• Theory - Understanding Diátaxis
• Foundations - Why Diátaxis works
• The map - Documentation in two dimensions
• Quality - Towards a theory of quality in documentation
• Tutorials and how-to guides - The difference between them
• Reference and explanation - The difference between them
• Complex hierarchies - Diátaxis in complex hierarchies

About

• Colophon - About Diátaxis and its author

The map

Source: https://diataxis.fr/map/

Diátaxis presents a two-dimensional structure for organizing documentation rather than a simple list. This framework positions different documentation types in relationship to one another, creating a mental map where boundaries between categories clarify their distinctions.

The Problem of Structure

Documentation often fails due to architectural issues that extend beyond mere structural problems. Without a clear, generalized framework, creators typically organize content around product features — an approach that generates inconsistency across multiple documentation sets.

"Any orderly attempt to organise documentation into clear content categories will help improve it (for authors as well as users)." However, authors frequently struggle when content doesn't fit existing categories or when selecting between competing organizational schemes.

Expectations and Guidance

Clear organization provides two critical benefits: reader expectations and author guidance. The framework defines four documentation types:

Blur and Boundary Erosion

Documentation systems naturally exhibit "affinities between each of the different forms" and neighboring categories. When distinctions blur, documentation becomes less effective. The worst case involves tutorials and how-to guides collapsing into each other, undermining both formats' purposes.

The Cycle of Interaction

Diátaxis maps a documentation journey reflecting how users develop expertise:

1. Learning-oriented phase: Initial skill acquisition through guided practice 2. Goal-oriented phase: Applying learned skills to achieve objectives 3. Information-oriented phase: Consulting technical reference for needed knowledge 4. Explanation-oriented phase: Reflecting on practice and deepening understanding

This cycle repeats as users master new topics or deepen existing knowledge. Users may enter this cycle at any point based on their immediate needs.

Towards a theory of quality in documentation

Source: https://diataxis.fr/quality/

Diátaxis is an approach to _quality_ in documentation.

"Quality" is a word in danger of losing some of its meaning; it's something we all approve of, but rarely risk trying to describe in any rigorous way. We want quality in our documentation, but much less often specify what exactly we mean by that.

All the same, we can generally point to examples of "high quality documentation" when asked, and can identify lapses in quality when we see them - and more than that, we often agree when we do. This suggests that we still have a useful grasp on the notion of quality.

As we pursue quality in documentation, it helps to make that grasp surer, by paying some attention to it - here, attempting to refine our grasp by positing a distinction between functional quality and deep quality.

Functional quality

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.

Deep quality

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_.

What's the difference?

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. 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_.

How we recognise deep quality

Consider how we judge the quality of 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 things. 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 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. Good documentation feels good; you feel pleasure and satisfaction when you use it - it feels like it fits and moves with you.

Diátaxis and quality

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.

Exposing lapses in functional quality

Although Diátaxis cannot address, or _give_ us, functional quality, it can still serve it.

It works very effectively to _expose_ lapses in functional quality. It's often remarked that one effect of applying Diátaxis to existing documentation is that problems in it suddenly become apparent that were obscured before.

Creating deep quality

In deep quality on the other hand, the Diátaxis approach can do more.

For example, it helps documentation _fit user needs_ by describing documentation modes that are based on them; its categories exist as a response to needs.

We must pay attention to the correct organisation of these categories then, and the arrangement of its material and the relationships within them, the form and language adopted in different parts of documentation - as a way of fitting to user needs.

Or, in Diátaxis we are directly concerned with _flow_. In flow - whether the context is documentation or anything else - we experience a movement from one stage or state to another that seems right, unforced and in sympathy with both our concerns of the moment, and the way our minds and bodies work in general.

Diátaxis preserves flow by helping prevent the kind of disruption of rhythm that occurs when something runs across our purpose and steady progress towards it (for example when a digression into explanation interrupts a how-to guide).

Understanding the limits

It's important to understand that Diátaxis can never be _all_ that is required in the pursuit of deep quality. Diátaxis offers a set of principles - it doesn't offer a formula. It certainly cannot offer a short-cut to success, bypassing the skills and insights of disciplines such as user experience or user interaction design, or even visual design.

Using Diátaxis does not guarantee deep quality. The characteristics of deep quality are forever being renegotiated, reinterpreted, rediscovered and reinvented. But what Diátaxis _can_ do is lay down some conditions for the _possibility_ of deep quality in documentation.

The difference between reference and explanation

Source: https://diataxis.fr/reference-explanation/

Explanation and reference both belong to the _theory_ half of the Diátaxis map - they don't contain steps to guide the reader, they contain theoretical knowledge.

The difference between them is - just as in the difference between tutorials and how-to guides - the difference between the _acquisition_ of skill and knowledge, and its _application_. In other words it's the distinction between _study_ and _work_.

A straightforward distinction, mostly

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.

...but intuition isn't reliable enough

Mostly we can rely safely on intuition to manage the distinction between reference and explanations. But only _mostly_ - because it's also quite easy to slip between one form and the other.

It usually happens while writing reference material that starts to become expansive. For example, it's perfectly reasonable to include illustrative examples in reference (just as an encyclopaedia might contain illustrations) - but examples are fun things to develop, and it can be tempting to develop them into explanation (using them to say _why_, or show _what if_, or how it came to be).

As a result one often finds explanatory material sprinkled into reference. This is bad for the reference, interrupted and obscured by digressions. But it's bad for the explanation too, because it's not allowed to develop appropriately and do its own work.

Work and study

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 to 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.

Reference

Source: https://diataxis.fr/reference/

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

---

Reference material contains _propositional or theoretical_ knowledge that a user looks to in their _work_.

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 as description

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.

---

Key principles

Describe and only describe

_Neutral description_ is the key imperative of technical reference.

Unfortunately one of the hardest things to do is to describe something neutrally. It's not a natural way of communicating. What's natural on the other hand is to explain, instruct, discuss, opine, and all these things run counter to the needs of technical reference, which instead demands accuracy, precision, completeness and clarity.

It can be tempting to introduce instruction and explanation, simply because description can seem too inadequate to be useful, and because we do indeed need these other things. Instead, link to how-to guides, explanation and introductory tutorials.

Adopt standard patterns

Reference material is useful when it is consistent. Standard patterns are what allow us to use reference material effectively. Your job is to place the material that your user needs know where they expect to find it, in a format that they are familiar with.

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.

Respect the structure of the machinery

The way a map corresponds to the territory it represents helps us use the former to find our way through the latter. It should be the same with documentation: the structure of the documentation should mirror the structure of the product, so that the user can work their way through them at the same time.

It doesn't mean forcing the documentation into an unnatural structure. What's important is that the logical, conceptual arrangement of and relations within the code should help make sense of the documentation.

Provide examples

Examples are valuable ways of providing illustration that helps readers understand reference, while avoiding the risk of 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, without falling into the trap of trying to explain or instruct.

---

The language of reference guides

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.

---

Applied to food and cooking

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.

Start here - Diátaxis in Five Minutes

Source: https://diataxis.fr/start-here/

The Four Kinds of Documentation

Diátaxis identifies four fundamental documentation types serving different purposes:

Tutorials: A tutorial is a lesson, that takes a student by the hand through a learning experience. Tutorials are practical, with learners performing tasks under guidance. Example: "Let's create a simple game in Python."

How-to Guides: These address a real-world goal or problem, by providing practical directions. Unlike tutorials, how-to guides target competent users handling actual work rather than learning.

Reference: Reference documentation provides the technical description - facts - that a user needs in order to do things correctly. This material remains neutral and factual, structured like maps reflecting the subject's architecture.

Explanation: These guides provide context and background and answer the question "why?" They help users understand bigger pictures and connections.

The Diátaxis Framework

The framework uses two axes:

• Action vs. Cognition: Tutorials and how-to guides involve doing; reference and explanation involve understanding
• Acquisition vs. Application: Tutorials and explanation support learning; how-to guides and reference support working

The Compass Table

Practical Workflow

The recommended approach involves:

1. Examining current documentation 2. Identifying improvement opportunities 3. Selecting one small improvement 4. Implementing it 5. Repeating the process

Key Principle

The framework emphasizes pragmatism: "You don't have to believe in it and there is no exam." Users benefit most when consulting this guidance during actual documentation challenges.

Understanding Diátaxis

Source: https://diataxis.fr/theory/

"The Grand Unified Theory of Documentation" — David Laing

---

The pages in this section are intended to provide some theoretical grounding for the practices Diátaxis prescribes, and to explore some of the questions it raises.

Within the discipline of documentation, discourse tends towards the practical and concrete. The approach is generally heuristic: guidelines, rules of thumb, specific imperatives, principles that we know work.

As practitioners, we have much to say about what to do, and how to do it and how it works, and relatively little to say about _why_ it works. Our sense of the right way to do things is largely based on a combination of intuition and experience. The theoretical aspect of the discipline receives far less attention.

Diátaxis aims to place documentation practice on a more rigorous theoretical footing.

---

In this section

These pages dig deeper into the thinking that underpins Diátaxis.

• Foundations - _why_ Diátaxis works
• The map - documentation in two dimensions
• Towards a theory of quality in documentation

Common problems explored:

• The difference between a tutorial and how-to guide
• The difference between reference and explanation
• Diátaxis in complex hierarchies

The difference between a tutorial and how-to guide

Source: https://diataxis.fr/tutorials-how-to/

Core Distinction

The fundamental difference centers on user needs. "Sometimes the user is at study, and sometimes the user is at work." Tutorials serve learners acquiring skills, while how-to guides assist practitioners applying existing competence.

Key Characteristics

Tutorials are learning-oriented:

• Provide structured, safe learning experiences
• Eliminate unexpected challenges
• Offer a single, carefully-managed path
• Assume no prior familiarity
• Teacher bears responsibility for success
• Teach general principles applicable across situations

How-to guides are task-oriented:

• Direct already-competent users through specific tasks
• Prepare for real-world complications
• Branch with conditional alternatives ("if this, then that")
• Assume existing familiarity
• User bears responsibility for outcomes
• Focus on completing particular objectives

Why Confusion Occurs

Both formats involve step-by-step directions, making them superficially similar. However, confusing them creates problems. "A clinical manual that conflated education with practice...would be a literally deadly document."

Complexity Isn't the Distinguisher

Importantly, tutorials can address advanced topics, and how-to guides can cover basic procedures. The distinction depends on whether documentation serves "the user's study" or "their work," not complexity level.

The test

Ask yourself: is this documentation for someone who is learning (at study), or for someone who is working (applying what they know)?

• If learning → Tutorial
• If working → How-to guide

This is the only question that matters. Everything else follows from it.

Tutorials

Source: https://diataxis.fr/tutorials/

A tutorial is an experience that takes place under the guidance of a tutor. A tutorial is always learning-oriented.

---

A tutorial is a _practical activity_, in which the student learns by doing something meaningful, towards some achievable goal.

A tutorial serves the user's _acquisition_ of skills and knowledge - their study. Its purpose is not to help the user get something done, but to help them learn.

A tutorial in other words is a lesson.

It's important to understand that while a student will learn by doing, what the student _does_ is not necessarily what they _learn_. Through doing, they will acquire theoretical knowledge (i.e. facts), understanding, familiarity. They will learn how things relate to each other and interact, and how to interact with them. They will learn the names of things, the use of tools, workflows, concepts, commands. And so on.

---

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 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.

Obligations of the teacher

A lesson is a kind of contract between teacher and student, in which nearly all the responsibility falls upon 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. Meanwhile, the only responsibility of the pupil in this contract 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.

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

The problem of tutorials

In general, tutorials are rarely done well, partly because they are genuinely difficult to do well, and partly because they are not well understood. In software, many products lack good tutorials, or lack tutorials completely; tutorials are often conflated with how-to guides.

In an ideal lesson, the teacher is present and interacts with and responds to the student, correcting their mistakes and checking their learning. In documentation, none of this is possible.

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.

You will also often find that no other part of your documentation is subject to revisions the way your tutorials are. Elsewhere in documentation, changes and improvements can generally be made discretely; in tutorials, where the end-to-end learning journey must make sense, they often cascade through the entire story.

Finally, tutorials contain the additional complication of the distinction between _what is to be learned_ and _what is to be done_. Not only must the creator of a tutorial have a good sense of what the user must learn, and when, they must also devise a meaningful learning journey that somehow delivers all that.

---

Key principles

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.

Show the learner where they'll be going

It's important to allow the learner to form an idea of what they will achieve right from the start. As well as helping to set expectations, it allows them to see themselves building towards the completed goal as they work.

Providing the picture the learner needs in a tutorial can be as simple as informing them at the outset: _In this tutorial we will create and deploy a scalable web application. Along the way we will encounter containerisation tools and services._

This is not the same as saying: _In this tutorial you will learn..._ - which is presumptuous and a very poor pattern.

Deliver visible results early and often

Your learner is probably doing new and strange things that they don't fully understand. Understanding comes from being able to make connections between causes and effects, so let them see the results and make the connections rapidly and repeatedly. Each one of those results should be something that the user can see as meaningful.

Every step the learner follows should produce a comprehensible result, however small.

Maintain a narrative of the expected

At every step of a tutorial, the user experiences a moment of anxiety: will this action produce the correct result? Part of the work of a successful tutorial is to keep providing feedback to the learner that they are indeed on the right path.

Keep up a narrative of expectations: "You will notice that..."; "After a few moments, the server responds with...". Show the user actual example output, or even the exact expected output.

If you know in advance what the likely signs of going wrong are, consider flagging them: "If the output doesn't show..., you have probably forgotten to...".

It's helpful to prepare the user for possibly surprising actions: "The command will probably return several hundred lines of logs in your terminal."

Point out what the learner should notice

Learning requires reflection. This happens at multiple levels and depths, but one of the first is when the learner observes the signs in their environment. In a lesson, a learner is typically too focused on what they are doing to notice them, unless they are prompted by the teacher.

Your job as teacher is to close the loops of learning by pointing things out, in passing, as the lesson moves along. This can be as simple as pointing out how a command line prompt changes, for example.

Observing is an active part of a craft, not a merely passive one. It means paying attention to the environment, a skill in itself. It's often neglected.

Target the feeling of doing

In all skill or craft, the accomplished practitioner experiences a _feeling of doing_, a joined-up purpose, action, thinking and result.

As skill develops, it flows in a confident rhythm and becomes a kind of pleasure. It's the pleasure of walking, for example.

Your learner's skill depends upon their discovering this feeling, and its becoming a pleasure.

Your challenge as the creator of a tutorial is to ensure that its tasks tie together purpose and action so they become a cradle for this feeling.

Encourage and permit repetition

Learners will return to and repeat an exercise that gives them success, for the pleasure they find in getting the expected result. Doing so reaffirms to them that they can do it, and that it works.

Repetition is a key to establishing the feeling of doing; being at home with that feeling is a foundational layer of learning.

In your tutorial, try to make it possible for a particular step and result to be repeated.

Ruthlessly minimise explanation

_A tutorial is not the place for explanation._ In a tutorial, the user is focused on correctly following your directions and getting the expected results. _Later_, when they are ready, they will seek explanation, but right now they are concerned with _doing_. Explanation distracts their attention from that, and blocks their learning.

For example, it's quite enough to say something like: _We're using HTTPS because it's more secure._ There is a place for extended discussion and explanation of HTTPS, but not now. Instead, provide a link or reference to that explanation, so that it's available, but doesn't get in the way.

... and focus on the concrete

In a learning situation, your student is in the moment, a moment composed of concrete things. You are responsible for setting up and maintaining the student's flow, from one concrete action and result to another.

Focus on _this_ problem, _this_ action, _this_ result, in such a way that you lead the learner from step to concrete step.

It might seem that by maintaining focus on the concrete and particular that you deny the student the opportunity to see or grasp the larger general patterns, but the contrary is true. The one thing our minds do spectacularly well is to perceive general patterns from concrete examples. All learning moves in one direction: from the concrete and particular, towards the general and abstract. The latter _will_ emerge from the former.

Ignore options and alternatives

Your job is to guide the learner to a successful conclusion. There may be many interesting diversions along the way (different options for the command you're using, different ways to use the API, different approaches to the task you're describing) - ignore them. _Your guidance needs to remain focused on what's required to reach the conclusion_, and everything else can be left for another time.

Aspire to perfect reliability

A tutorial must inspire confidence. Confidence can only be built up layer by layer, and is easily shaken. At every stage, when you ask your student to do something, they must see the result you promise. A learner who follows your directions and doesn't get the expected results will quickly lose confidence, in the tutorial, the tutor and themselves.

Your tutorial ought to be so well constructed that things _can't_ go wrong, that your tutorial works for every user, every time.

---

The language of tutorials

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.

---

Applied to food and cooking

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.