One reader is learning your product, another is debugging it at 2am. How do you structure documentation that serves both?

Short answer

Use a Diataxis documentation structure: tutorials for learning, how-to guides for tasks, reference for lookup and explanation for understanding. The key is reader intent, because a learner needs one guided path while a debugging reader needs dense, searchable facts with narrative removed.

The two readers want opposite things

The learner has no model of the system yet and no way to evaluate a choice, so every option you offer is a decision they cannot make. What they need is one narrated path that works, in order, with the outcome stated at each step, and with alternatives deliberately withheld. The value is that it finishes.

The person debugging at 2am has a model already and one specific unknown: what the third value of this enum means, or which error the gateway returns when the upstream times out. Narrative is an obstacle to them. They need density, headings that match the words they would search for, exhaustive rather than illustrative coverage, and no prose between the thing they want and the page top.

Serve both on one page and you get the page every mature product has: a tutorial with eleven parenthetical asides about production configuration, which the learner cannot finish and the debugger cannot scan. Neither reader is served, and the page keeps growing because every new option has an obvious place to be inserted.

Splitting by intent, not by component

The instinct is to organise documentation by the shape of the system - one page per service, one page per module. That mirrors your architecture and mirrors nothing about why anyone arrived. Intent-first structure asks instead what the reader is doing at the moment they open the page: acquiring a skill, completing a task, looking something up, or trying to understand why the thing works as it does.

That is the Diataxis four-mode framework - tutorial, how-to guide, reference, explanation - and its usefulness is that the four are defined by an actual pair of axes rather than by taste. Tutorials and how-to guides serve action; reference and explanation serve cognition. Tutorials and explanation are approached at study time; how-to guides and reference are approached in the middle of work.

flowchart TD
  R[Reader arrives] --> A{Acting or understanding}
  A -->|Acting| B{New skill or known task}
  A -->|Understanding| C{At work or at study}
  B -->|New skill| T[Tutorial<br/>one path, no options]
  B -->|Known task| H[How-to<br/>goal-shaped, assumes context]
  C -->|At work| F[Reference<br/>exhaustive, scannable]
  C -->|At study| E[Explanation<br/>why it is like this]

The interesting edge is the split on the right: reference and explanation both answer "how does this work", and the difference is only whether the reader is mid-task. That is the boundary teams get wrong most often, by putting design rationale into reference pages where the 2am reader has to step over it.

What each mode forbids

The rule that makes this work is subtractive. A tutorial may not offer a choice. A how-to guide may not teach the underlying model - it assumes you have one and gets you to a goal. Reference may not narrate; it describes what is, in the structure of the thing itself, and it is the only mode where completeness matters more than readability. Explanation may not contain steps, because as soon as it does, readers follow them and it becomes an untested procedure.

Applied to a single bloated page, the split is mechanical:

The cost, which a strong answer volunteers

Four modes means four places to update when behaviour changes, and the failure mode is a corrected reference page beside a tutorial that still shows the old flag. It also means contributors no longer know where to put things: an engineer with a paragraph to add now faces a taxonomy question before they can write, and the usual result is that the paragraph lands in whichever page they read most recently. You buy that back with a contributing guide that describes the four modes in terms of the reader, plus a reviewer who is willing to move a paragraph rather than reject it.

The subtler cost is that most readers never see your navigation at all. They arrive from a search engine, in the middle, on a page whose mode they cannot infer. That is why each page needs a title that states the task rather than the topic, an opening line that says who the page is for and what it assumes, and an explicit link to its sibling in the other mode - the tutorial linking the reference table, the reference row linking the how-to. Without those, a correct four-mode structure reads to an arriving reader as four disconnected fragments.

Where reciting the framework fails

Naming the four modes is table stakes and most candidates get there. What separates a strong answer is being able to say what you would delete: that the production caveat has to come out of the tutorial even though it is true and important, because a tutorial that hedges does not get finished. Interviewers push on exactly this, because the willingness to remove correct information from a page is the part that only comes from having watched readers fail.

Structure follows the reader's intent at the moment of arrival, and the hardest part of applying it is taking accurate content off a page that no longer needs it.

© 2026 Preptima. Originally published at preptima.com.