Documentation Types: Tutorial, How-To, Reference, and Explanation

By the end of this lesson, you will be able to...

• Classify a documentation need as tutorial, how-to, reference, or explanation from the reader's situation.

• Distinguish types that look similar, especially tutorial from how-to and reference from explanation.

• Split an overloaded technical page into focused documents with clear promises and links.

Idea in one sentence: Choose a document's shape from what the reader is doing now—learning, completing a task, looking up a fact, or building understanding.

Core Insight

The team behind Pulse, a small service-health command-line tool, has written one page called “Getting Started.”

The page contains:

• installation steps
• a guided exercise with a demo service
• production authentication options
• a table of every command and flag
• a procedure for adding a health check
• a discussion of why Pulse waits for three samples
• error codes
• design alternatives

Nothing on the page is obviously wrong. Almost every reader still feels that the page is in the way.

A new engineer follows two steps, reaches a long options table, and cannot tell what to do next.

An experienced operator searches for the timeout flag and must scroll through the demo exercise.

An engineer adding a production check finds several pages of background before the required procedure.

A reviewer who wants to understand the three-sample rule finds only one unexplained sentence beside a command.

The team organized the page around one product. The readers arrive with four different needs.

The first lesson gave us a reader promise. That promise answers, “What should this reader be able to do differently?” This lesson adds the next design decision: which document mode can keep that promise?

Why One Complete Page Breaks

The naive model is attractive:

  put all useful information about Pulse in one complete page
  -> readers have everything in one place
  -> nobody needs to search elsewhere

This works while the page is small and every reader follows roughly the same path.

It breaks when readers use the material in different ways.

A learner needs a safe sequence. Interrupting that sequence with every option increases cognitive load.

An operator needs a fact now. A long narrative delays retrieval.

A practitioner solving a real problem needs actions and branches. A lesson that removes choices may be too controlled for production.

A reader building a mental model needs reasons, connections, and trade-offs. A command table cannot develop those ideas.

Completeness is not one property. A complete tutorial contains a complete learning experience. A complete reference describes the relevant interface. Those are different obligations.

Two Questions Reveal Four Modes

Ask two questions about the reader's situation.

First:

  Is the reader studying, or working?

• Studying means acquiring knowledge or skill. The reader can pause, experiment, and reflect.
• Working means applying existing skill to a real task. The reader needs progress or a reliable fact.

Second:

  Does the reader need guided action, or theoretical knowledge?

• Guided action tells the reader what to do.
• Theoretical knowledge tells the reader what exists, how it behaves, or why it has that shape.

Together, the questions produce four modes:

Plain meaning:

The four modes are four answers to four different reader needs.

In the Pulse scenario:

The same command can appear in a guided first experience, a production procedure, an options table, or a discussion of a design decision. Its role changes with the reader's need.

Technical name:

We will call tutorial, how-to, reference, and explanation documentation modes. A mode is the dominant promise and organizing logic of a document.

Tutorial: Guide a Learning Experience

A tutorial serves a reader who is learning through action.

The learner does not yet have enough experience to choose a good path. The tutorial chooses one. It controls the environment, removes unnecessary alternatives, shows expected results, and produces small successes.

For Pulse, a tutorial might be:

Tour Pulse with a demo service

Install Pulse, start the supplied demo service, run one health check, change the demo response, and observe how the status changes after three samples.

The important result is not that the demo service was checked. The result is that the learner has encountered installation, a command, output, state change, and the three-sample behavior in a reliable sequence.

A strong tutorial:

• starts from declared prerequisites
• uses a safe and repeatable environment
• follows one path rather than presenting many choices
• produces visible results early
• says what the learner should notice
• accepts some incompleteness to protect the learning flow

A tutorial can teach an advanced topic. “Tutorial” does not mean “basic.” It means the reader is in a learning situation and the document takes responsibility for the path.

How-To: Guide Real Work

A how-to guide serves a competent reader who wants to accomplish a specific real-world task.

The reader already knows the general tools. They do not need a tour. They need a route through constraints, preconditions, actions, checks, and possible branches.

For Pulse, a how-to might be:

Add a Pulse check to an authenticated production service

Confirm that the service exposes the health endpoint. Create a restricted token. If the service uses mutual TLS, configure the client certificate; otherwise, configure the bearer token. Add the check, run it manually, and verify the first three samples before enabling alerts.

The guide assumes the reader knows what a health check and an authentication token are. It spends its space on the task and its branches.

A strong how-to:

• names a concrete goal or problem
• assumes baseline competence
• starts and ends at meaningful points in real work
• uses actions, conditions, warnings, and verification
• leaves background explanation elsewhere
• links to reference for exhaustive options

Tutorials and how-to guides both contain steps. The difference is not steps versus no steps. The difference is the reader's situation: acquiring competence or applying competence.

Check: A senior engineer follows a guided lab to learn a new failure-injection tool. Is the lab a tutorial or a how-to?

Think first, then reveal.

Answer: It is a tutorial. The engineer may be highly experienced, but in this situation they are studying. Difficulty and seniority do not determine the mode.

Reference: Make Facts Easy to Retrieve

Reference serves a reader who is working and needs authoritative information.

The reader rarely wants a beginning-to-end story. They want to locate one fact, verify it, and return to the task.

For Pulse, a reference page might be:

pulse check command

Synopsis, arguments, flags, defaults, environment variables, output fields, exit codes, limitations, and one compact invocation example.

Reference follows the structure of the thing it describes. Command documentation follows commands and flags. API reference follows resources, fields, requests, responses, and errors.

A strong reference:

• is factual, precise, and consistent
• supports scanning and lookup
• uses stable patterns across similar entries
• states defaults, boundaries, errors, and constraints
• includes examples that illustrate facts without turning into a lesson
• avoids long arguments and procedural detours

An example does not automatically turn reference into a how-to. A one-line invocation can clarify a flag. The page remains reference if its main promise is accurate retrieval.

Explanation: Build a Connected Mental Model

Explanation serves a reader who has stepped back from immediate action and wants to understand.

The reader asks why the system behaves as it does, how concepts connect, which alternatives were possible, or what trade-off shaped a decision.

For Pulse, an explanation might be:

Why Pulse waits for three health samples

A single failed request may be noise. Waiting for three samples reduces unstable state changes, but it also delays detection. This article compares one-sample, consecutive-sample, and rolling-window rules, then explains why Pulse chose its default.

Explanation can discuss history, causality, mechanisms, analogies, alternatives, and consequences. Unlike reference, it is organized around a bounded question rather than the product's interface.

A strong explanation:

• begins with a real why or how question
• connects facts into a mental model
• makes mechanisms and trade-offs visible
• compares alternatives or perspectives
• sets a boundary so the topic does not expand forever
• links to procedures and exact facts instead of absorbing them

Reference and explanation both contain knowledge rather than a guided task. The difference is use. Reference supports work through exact facts. Explanation supports study through connections and reasons.

Check: A command reference contains a small example showing the default timeout. Does that example make the page an explanation?

Think first, then reveal.

Answer: No. The example illustrates an exact fact and helps lookup. It would become explanatory if it developed why the timeout has that value, compared alternatives, and explored consequences.

A Worked Split of the Pulse Page

Return to the overloaded “Getting Started” page. We can now classify each content fragment by the reader's dominant need.

Now trace the design decision:

  overloaded source page
  -> reader promise from lesson 001
  -> study or work
  -> action or theoretical knowledge
  -> documentation mode
  -> structure and success test

Each resulting document has a different success test:

The team has not deleted useful content. It has given each piece a stable home.

Mixing, Linking, and Small Documents

Real documents can contain small elements from other modes.

A tutorial can link to explanation after a learner sees the behavior. A how-to can include one short reason when it prevents an unsafe action. Reference can include compact examples. Explanation can include a tiny trace.

The useful rule is:

  let one mode control the main path
  let other modes support it without taking over

When another need requires a different reading behavior, split and link.

For example, an operator scanning exit codes should not cross three paragraphs of design history. Link “Why exit code 3 means degraded” to an explanation. A learner following a demo should not choose among nine authentication systems. Link the production how-to after the controlled success.

Trade-offs and Limits

Separating modes improves reader fit, but it increases coordination work.

The central trade-off is focus versus fragmentation. Focused documents give readers cleaner paths. More documents create more navigation, links, ownership, and opportunities for inconsistency.

Over-segmentation is visible when readers must open several pages to complete one small task and each page repeats the same prerequisites. Under-segmentation is visible when a page repeatedly changes pace: lesson, command table, background essay, procedure, then lesson again.

The four modes do not answer every information-architecture question. They do not decide navigation labels, ownership, versioning, localization, or whether two very short items deserve separate URLs. They provide a diagnostic model for reader needs.

Do not force the public navigation to use the four mode names. Product language may be clearer. “First health check,” “Configure authentication,” “CLI commands,” and “Health-state model” can be better labels than “Tutorial,” “How-to,” “Reference,” and “Explanation.”

Common Confusions

Confusion: Tutorials are basic; how-to guides are advanced

Why it is tempting:

Learners often begin with tutorials and later use how-to guides.

Better model:

The difference is study versus work. An advanced practitioner can take a difficult tutorial. A basic recurring task can need a how-to guide.

Confusion: A page with steps is a how-to

Why it is tempting:

Procedures are the most visible feature of how-to guides.

Better model:

Tutorials also contain steps. Ask whether the page creates a controlled learning experience or guides competent action in a real situation.

Confusion: Reference is all the documentation

Why it is tempting:

Generated API pages can cover the entire interface and look complete.

Better model:

Interface completeness serves lookup. It does not provide a first learning path, solve a reader's real project, or explain why the system behaves as it does.

Confusion: Explanation is an introduction before the real content

Why it is tempting:

Background sections are often short and placed first.

Better model:

Explanation has its own promise: a connected understanding of a bounded question. It deserves enough space to develop mechanisms, reasons, alternatives, and trade-offs.

Practice: Split a Queue Client Page

A queue client page contains these fragments:

1. Install the client and send one message to a supplied local queue.
2. Show the expected confirmation and point out the message identifier.
3. Configure retries for an existing production worker.
4. Branch between fixed and exponential backoff.
5. List every retry field, type, default, and valid range.
6. Show the error returned when the retry limit is invalid.
7. Explain why jitter reduces synchronized retry bursts.
8. Compare full, equal, and decorrelated jitter.

Create four document cards. For each card, write:

• mode
• title
• primary reader situation
• reader promise
• fragments it owns
• one link to another mode

A good answer should:

• place fragments 1–2 in a tutorial with a controlled, observable success
• place fragments 3–4 in a how-to for a competent reader doing production work
• place fragments 5–6 in reference organized for lookup
• place fragments 7–8 in explanation organized around why and trade-offs
• avoid copying every fragment into every document
• preserve one clear main path in each document
• use links where the reader's need changes

Connections

Lesson 001 supplied the reader promise. This lesson uses that promise to choose a document mode. Lesson 003 will work inside explanations and tutorials by showing when a concrete situation should appear before an abstract term.

Resources

• [REFERENCE] Diátaxis — Focus: the four documentation needs and the relationship among tutorial, how-to, reference, and explanation.
• [ARTICLE] The Difference Between a Tutorial and How-To Guide — Focus: study versus work, controlled learning paths, and real-world task guidance.
• [ARTICLE] The Difference Between Reference and Explanation — Focus: exact information used during work versus connected understanding built during study.
• [COURSE] Organizing Large Documents — Google Technical Writing — Focus: reader behavior, progressive disclosure, introductions, and splitting large material into usable paths.

Key Takeaways

• Tutorial, how-to, reference, and explanation serve different reader situations, even when they discuss the same product.
• Tutorials guide learning; how-to guides direct real work; reference supports exact lookup; explanation builds connected understanding.
• Steps do not distinguish tutorials from how-to guides, and examples do not stop reference from being reference.
• A document mode is the dominant promise, organization, and success test—not merely a title or page template.
• Splitting modes creates maintenance cost, so keep one clear main path and use links when the reader's need changes.