Diataxis Check

Diátaxis Check

Review one existing documentation page or small fragment.

The goal is to determine:

• what the page appears to help its intended reader do or understand;
• what kind of documentation would best serve that need;
• whether the page's scope, structure, and content support that purpose;
• what single change would improve it most.

Use Diátaxis as a reasoning framework, not as a compliance checklist.

Terminology

Keep these roles distinct:

• Requester — the person asking for the review.
• Reader or intended reader — the person the documentation itself is meant to serve.

When reasoning about needs, competence, work, study, goals, or understanding, refer to the documentation reader, not the requester.

Scope

By default, review one page or a small supplied fragment.

Focus on page-level content design:

• purpose;
• reader need;
• scope;
• grouping;
• sequence or organization;
• fit between the reader need and the documentation form;
• placement of supporting material;
• interruptions to the reader's current purpose.

Do not automatically expand the review into a site-wide information architecture analysis.

If only a fragment is supplied, make claims only about that fragment unless the surrounding page is visible.

Establish the reader situation

Do not treat the page as authoritative evidence of its own intended purpose.

Keep two things distinct:

• Intended reader and outcome — who the documentation is supposed to serve and what it is supposed to help them accomplish or understand.
• Apparent reader and outcome — who the page itself appears to serve and what it appears to help them accomplish or understand.

Use evidence in this order:

1. requester-provided context about the intended audience, goal, workflow, or desired outcome;
2. other explicit context supplied with the page;
3. evidence from the page itself.

When the requester provides an intended reader or outcome, treat that context as the evaluation target. Do not silently replace it with a different purpose inferred from the page.

When the intended reader or outcome is not known, infer the apparent reader situation from the page, but treat that inference as a hypothesis rather than ground truth.

If materially different plausible purposes would lead to different review results, ask the requester for the missing context before giving an overall positive or negative judgement.

A coherent page can still be the wrong page for its intended purpose.

The reader need is situational.

An experienced practitioner can be studying something unfamiliar. A beginner can be performing real work. Do not equate tutorial with beginner or how-to with advanced.

Try to state the need in reader terms.

Prefer:

• configure session timeout;
• rotate an API key;
• understand why deployments are immutable;
• look up the parameters of an endpoint;
• learn to create and deploy a first project.

Avoid treating a product object as a reader need.

For example:

Visual Workflow Editor

names a product object.

Change a workflow and apply it to the portal

describes a reader goal.

Use the Diátaxis compass

Classify the reader situation along two dimensions:

Ask both questions:

1. Does the reader primarily need action or cognition?
2. Is the reader acquiring skill or knowledge, or applying existing skill or knowledge?

Use the terms as practical distinctions:

• Action — practical steps, doing, knowing how.
• Cognition — theoretical or propositional knowledge, knowing that, thinking.
• Acquisition — study.
• Application — work.

Do not decide from one axis alone.

For example:

• both tutorials and how-to guides concern action;
• both how-to guides and reference serve work;
• both reference and explanation concern cognition;
• both tutorials and explanation serve study.

The second axis is often what resolves an apparent similarity.

Apply the compass to both need and content

Use the compass in two separate ways.

First, determine what the reader needs.

Then inspect what the page actually does.

Do not assume that authorial intent, navigation placement, title, and actual content necessarily agree.

A page can be called a tutorial while functioning as task guidance. A page placed under reference can contain a substantial conceptual discussion.

The mismatch between the reader situation and the actual content is often more useful than the label itself.

Use the compass at the necessary scale

Establish the page's primary job at whole-page level.

When a particular section or passage appears to interfere with that job, apply the same distinctions locally.

A page can contain local material that serves another Diátaxis need.

Do not treat that fact alone as a defect.

Ask whether the local material supports the page's primary job or creates a substantial competing need.

Load the relevant mode guidance

After inferring the reader situation, read the corresponding diagnostic reference:

• Tutorial — references/tutorial.md
• How-to guide — references/how-to.md
• Reference — references/reference.md
• Explanation — references/explanation.md

Read the expected dominant mode's reference before evaluating the page in detail.

Do not read all four by default.

Read a second reference when:

• the reader need remains genuinely ambiguous between two modes;
• the page substantially serves two competing needs;
• a neighboring-mode distinction is necessary to diagnose the problem.

Use the reference to establish concrete expectations for the page's purpose, scope, organization, reader assumptions, and boundaries.

Review workflow

1. Establish the evaluation target

Keep the document's intended purpose separate from its apparent purpose.

The intended purpose is the external reason this document is supposed to exist: who it is meant to serve, in what situation, and what outcome it is supposed to produce.

The apparent purpose is what the document itself appears or claims to help the reader do or understand.

Never establish the intended purpose from the document under review itself.

Statements in the page title, introduction, headings, navigation, or body about who the page is for or what it will accomplish are evidence of the page's apparent purpose only. They are not independent evidence that this is the correct purpose for the page.

Establish the intended purpose only from requester-provided or other external context.

If external context provides an intended reader or outcome, use it as the evaluation target and compare the page's apparent purpose against it.

If no external intended purpose is available, do not infer one. Continue by evaluating the page against its apparent purpose, but explicitly limit the conclusion to internal coherence. Do not conclude that the page is appropriate for its real documentation or product goal.

Then inspect the page to determine its apparent reader and outcome using:

• title and introduction;
• headings;
• actions the reader is asked to perform;
• information the reader is expected to consult;
• questions the page appears to answer;
• assumptions about existing competence;
• expected outcome or understanding.

For action-oriented documentation, state the apparent outcome as a concrete end state: what has the reader accomplished, produced, configured, or become able to do by the end?

For cognition-oriented documentation, state what the reader should understand or be able to reason about by the end.

If several substantial apparent reader needs are present, preserve that finding rather than inventing one artificial purpose.

2. Determine the expected mode

Apply both compass dimensions to the reader situation.

Use the result to establish what kind of documentation should serve that need.

Classification is a hypothesis about the page's obligations, not the review result.

3. Read the relevant diagnostic model

Load the corresponding reference.

Use it to establish what should determine:

• the page's scope;
• the page's structure;
• the reader assumptions;
• the type of progression or organization;
• appropriate supporting material;
• likely neighboring-mode failures.

4. Check purpose fit before mode fit

If an externally established intended purpose is available, first compare it with the page's apparent purpose.

A mismatch between intended and apparent purpose takes precedence over Diátaxis mode quality.

A document can be an excellent tutorial, how-to guide, reference page, or explanation and still be the wrong document for the intended reader outcome.

If no external intended purpose is available, do not make a positive judgement about purpose fit. Evaluate only whether the page is internally coherent relative to the purpose it appears to pursue.

Then ask whether the page serves the intended reader need, when known, in the way that the expected mode requires.

For action-oriented documentation, state the concrete end state and check whether each major section advances the reader toward that same end state.

Do not mistake a sequence of individually valid actions for a coherent journey. Several feature demonstrations, tasks, or visible results do not form one tutorial or how-to merely because they can be performed in sequence.

Look for concrete problems such as:

• the page's apparent purpose differs from its intended purpose;
• the page has no stable reader need;
• its major sections do not advance one coherent reader outcome;
• its scope follows a product or topic boundary that does not fit the reader situation;
• several independently meaningful tasks or subjects are bundled together;
• the organization follows the wrong logic for learning, working, consulting information, or building understanding;
• the page assumes substantially different levels of competence in different sections;
• a supporting passage creates a substantial competing reader need;
• material appears substantially before or after the point where the reader needs it;
• the page requires avoidable switching, backtracking, or interruption of the reader's current purpose.

Do not force every problem into the category of "mode mixing."

A page can be structurally weak while remaining entirely within one Diátaxis mode.

5. Check why the material belongs together

Ask why the page's major sections form one page.

A shared product feature, interface, object, or technical area is not by itself sufficient reason.

Check whether the grouping follows from the relevant reader need and mode.

Conversely, do not split a page merely because it contains:

• several actions;
• several interfaces;
• several examples;
• several roles;
• local material from another mode.

The question is whether those elements form one coherent experience for the intended reader.

6. Distinguish support from interference

Material from another mode can be useful support.

Examples:

• concise parameter information inside a how-to;
• a short reason inside a tutorial;
• a usage example inside reference;
• factual examples inside explanation.

Treat such material as a problem only when it substantially changes or interrupts what the reader is there to do.

Typical signs include:

• the reader must stop performing work and begin studying a separate subject;
• lookup information is obscured by discussion;
• a learner must process an extended conceptual digression before continuing;
• an explanation turns into a complete practical procedure;
• a supporting passage grows into an independently useful document.

Do not recommend moving material solely to achieve mode purity.

7. Identify the highest-value problem

Prefer a root problem that explains several symptoms.

For example:

• repeated awkward sections may follow from organizing a how-to around product features instead of a human project;
• missing expected results may reveal that a tutorial is being treated as a procedure rather than a managed learning experience;
• difficult lookup may follow from reference being written as continuous explanatory prose.

Do not produce a backlog of every possible improvement.

If the page serves the known intended reader and outcome coherently, say so.

If the intended purpose is only inferred from the page itself, phrase any positive judgement conditionally. Do not use the page's internal coherence as evidence that the inferred purpose is the correct purpose.

8. Recommend one next improvement

Recommend one next change that addresses the highest-value problem you identified.

Match the level of the recommendation to the level of the problem. Do not reduce a structural or purpose-level problem to a cosmetic or local edit merely to keep the recommendation small.

The recommendation should still be bounded enough to act on without requiring a complete redesign of the documentation.

Explain why this change follows from the reader situation and the diagnosed problem.

Do not produce a complete replacement or redesign unless the requester asks for one.

Treat friction as evidence, not proof

If a page is unusually difficult to classify or organize, or if supposedly appropriate material repeatedly feels hard to place, reconsider the reader need and expected mode.

Do not use intuition alone to override the compass.

At the same time, do not manufacture a mode conflict merely because a passage looks superficially different.

Use the reader situation to resolve the ambiguity.

Diátaxis is not a required top-level structure

Do not require documentation to contain four top-level sections named Tutorials, How-to, Reference, and Explanation.

Do not recommend creating empty mode sections merely to reproduce the map.

Diátaxis can be applied locally to existing documentation.

For this skill, improve the material in front of you rather than designing an ideal complete documentation system.

Quality limits

Diátaxis does not verify functional qualities such as:

• factual accuracy;
• technical correctness;
• completeness;
• consistency with the product;
• precision.

It also does not replace accessibility, SEO, visual design, UX, or other specialist review.

Applying Diátaxis can expose signs of functional-quality problems.

For example, a reference structure may reveal an apparent coverage gap, or removing explanation from a tutorial may reveal that the learner was expected to infer a missing step.

Treat such findings as evidence of a possible problem, not as verification.

This skill can judge fit to reader needs, mode-specific content design, and reader flow. These require judgement rather than numerical measurement.

Do not assign a Diátaxis compliance score or percentage.

Do not claim that correct use of Diátaxis proves general documentation quality.

Output

Write concise, natural editorial feedback.

When an externally established intended reader or outcome is available, start with that evaluation target and say whether the page is coherently designed around it.

When no external intended purpose is available, clearly distinguish the page's apparent purpose from an actually established intended purpose.

Do not say that a page "works well", "serves its reader well", "is appropriate for its audience", or make an equivalent unconditional positive judgement when the intended purpose has only been derived from the page itself.

In that case, limit the conclusion to internal coherence. For example:

This page is internally coherent as a tutorial for X. From the page alone, however, I cannot determine whether X is the outcome this documentation is actually supposed to serve.

If missing audience or outcome context could materially change the verdict, say what context is missing. Ask the requester for it when answering the question responsibly requires it.

If the page's apparent purpose materially differs from an externally established intended purpose, make that mismatch the primary finding even when the page follows its Diátaxis mode well internally.

Then explain the most important problem using concrete evidence from the page.

Recommend one practical next improvement and explain why it would better serve the intended reader or outcome.

Use Diátaxis terminology when it clarifies the diagnosis, but do not force the response into fields such as:

• Dominant mode
• Reader need
• Mode conflict
• Confidence
• Compliance score

Do not describe the internal review workflow, including applying the compass, classifying the mode, or consulting mode references, unless the requester explicitly asks for the reasoning or a formal Diátaxis analysis.

State the result of that reasoning directly in reader-centered terms.

Instead of:

I applied the compass and identified this as a how-to guide...

Prefer:

This page appears to help an experienced reader modify and publish a workflow.

If the requester explicitly asks for classification, a formal Diátaxis audit, or the underlying reasoning, provide the compass and mode analysis.