Chapter 26: Technical Tutorials and How-To Content: Teaching Through Writing

"What I cannot create, I do not understand." — Richard Feynman

Chapter Overview

Raj Patel fixed his README. The eleven people who couldn't install chronoparse—his small library that turns messy human date strings like "next Tuesday" and "3 days ago" into real timestamps—can now run the install command and copy a working example, because Chapter 25 taught him to build a front door a stranger could walk through. The issue tracker went quiet. He thought he was done. Then a new kind of issue appeared, and it stumped him: "I installed it and the quick-start works, but I'm building a log analyzer and I have no idea how to actually use this on a real file. Is there a tutorial or something? I don't even know where to start." Below it, three thumbs-up from three other people who'd hit the same wall. His README had gotten them in. It had not taught them to use the thing. And the more Raj looked, the more he realized his instinct—"I'll just add more to the README"—was exactly wrong. The README was already the right length for what it was. What these readers needed wasn't a longer front door. It was a different kind of document, with a different reader, a different promise, and a different shape.

This chapter is about the two documents people confuse most often in all of technical writing: the tutorial and the how-to guide. They look similar from the outside—both have numbered steps, both involve a reader doing something at a keyboard—so writers blur them together, and the blur is the single most common reason software documentation feels frustrating to use. The fix begins with a framework called Diátaxis (Tier 1, by Daniele Procida), which says that technical documentation serves four distinct needs and that a document trying to serve two of them at once serves neither. We'll spend the chapter on the two that get mixed up the most. A tutorial is learning-oriented: its reader is a beginner, and its job is to guarantee a success experience—to hold their hand from nothing to a working result so they finish thinking "I did it, I can do this." A how-to guide is task-oriented: its reader already knows the basics and has a specific problem to solve, so it assumes competence and gets out of the way. This is the book's own thesis—theme 1, writing is thinking—turned outward: to teach a concept through writing, you must first understand it well enough to see where a learner will fall, which means seeing past your own expertise to the gaps you've stopped noticing.

Here is the threshold this chapter asks you to cross: a tutorial guarantees success; a how-to assumes it. That one sentence sorts almost every decision you'll make—what to explain, what to leave out, whether to offer choices or forbid them, what tone to take. And it sets up the chapter's central enemy, the one Chapter 2 named and Chapter 22 made you fear: the curse of knowledge. In a tutorial it takes a specific, lethal form—the assumed step, the action you perform so automatically that you forget it's an action at all, the silent "save the file" or "activate the virtual environment" whose absence stalls a beginner at step 4 with no idea what went wrong. By the end of this chapter, you will be able to classify any document by its Diátaxis type, write a tutorial that carries a beginner to a guaranteed win, write a how-to that respects a competent reader's time, and hunt down the assumed step before it ambushes your reader—and you'll watch Raj turn that frustrated issue into a getting-started tutorial that works.

In this chapter, you will learn to:

• Use the Diátaxis framework to classify documentation into tutorial, how-to, reference, and explanation—and diagnose the "two documents fighting inside one" problem that mixing them creates.
• Write a learning-oriented tutorial that guarantees a success experience: one concrete goal, a single tested path, no unexplained choices, and a visible win.
• Write a task-oriented how-to that assumes competence, solves exactly one problem, and respects an expert reader's time.
• Find and fix the assumed step—the action you do automatically and forget to write—using a step trace and a real beginner.
• Structure teaching content with worked examples and code progression, and add screenshots that actually help instead of decorate.

📗 Software/CS track: This is a core chapter for you, and it completes the arc that began two chapters ago. Chapter 24 taught you to comment the why; Chapter 25 turned your project's front door (the README) into something a stranger can open; this chapter teaches the documents that take that stranger from "it installed" to "I can build with this." The Diátaxis framework here is the missing piece that explains why the README, the tutorial, and the API reference you wrote in Chapter 25 are genuinely different documents that must not be merged. Prioritize §26.1 (Diátaxis), §26.2–§26.3 (tutorial vs. how-to), and §26.5 (the assumed step)—these are the ideas you'll use every time you onboard a teammate or open-source a tool.

26.1 The Four Kinds of Documentation: The Diátaxis Framework

Start with a confession most documentation writers won't make: they don't know what kind of document they're writing. They sit down to "write the docs," produce a single growing file that tries to introduce the project, walk a beginner through it, list every option, explain the design philosophy, and answer common problems—all in one undifferentiated stream—and they cannot understand why readers keep complaining that it's both too much and not enough. It is too much for the beginner who wanted to be carried gently to a first success. It is not enough for the expert who wanted a quick answer and had to wade through a beginner's hand-holding to find it. The document fails everyone because it was trying to be everything.

The insight that dissolves this mess is that technical documentation isn't one thing—it's four things, and they have different readers, different purposes, and different shapes. This is the Diátaxis framework, articulated by Daniele Procida (Tier 1; the name is from the Greek for "arrangement"). It organizes documentation along two axes. The first axis asks: is the reader studying (acquiring skill, learning the territory) or working (applying skill they already have to get a job done)? The second axis asks: does the reader need practical knowledge (steps, action) or theoretical knowledge (understanding, explanation)? Cross those two axes and you get four quadrants, and every page of good documentation lives cleanly in exactly one of them.

Figure 26.1 (described): A two-by-two grid. The horizontal axis runs from "practical steps" on the left to "theoretical knowledge" on the right. The vertical axis runs from "serves study/learning" at the top to "serves work/doing-a-task" at the bottom. Top-left (study + practical) = Tutorial, labeled "learning-oriented." Bottom-left (work + practical) = How-to guide, labeled "task-oriented." Bottom-right (work + theoretical) = Reference, labeled "information-oriented." Top-right (study + theoretical) = Explanation, labeled "understanding-oriented." A caption beneath reads: the left half is action ("doing"); the right half is cognition ("knowing"). The top half serves the learner; the bottom half serves the practitioner already at work.

Here are the four, each defined by the reader's situation:

• Tutorial — learning-oriented. The reader is a beginner who wants to learn by doing. They don't yet know what they don't know. The tutorial's job is to take them by the hand through a concrete, complete activity and guarantee they succeed, so they leave with confidence and a foothold. Example: "Build your first web app in 20 minutes." The reader is studying, and they need to act.
• How-to guide — task-oriented. The reader is a competent practitioner with a specific goal: they already know the basics and now need to accomplish one particular thing. The how-to gives them the recipe for that goal and nothing else. Example: "How to configure HTTPS for your deployment." The reader is working, and they need to act.
• Reference — information-oriented. The reader needs to look something up: the exact signature of a function, the full list of configuration options, every field of an API response. Reference is the dictionary—accurate, complete, austere, consulted not read. Example: an API endpoint specification (you wrote one in Chapter 25). The reader is working, and they need to know, not do.
• Explanation — understanding-oriented. The reader wants to understand why: the design rationale, the trade-offs, the background, the bigger picture. Explanation is the document you read in an armchair, away from the keyboard, to deepen your grasp. Example: "Why chronoparse uses a grammar engine instead of regular expressions." The reader is studying, and they need to know, not do. (This is the natural home for the Architecture Decision Record's reasoning from Chapter 25.)

Look at the difference between two documents that share a topic to feel how distinct the modes are. Both are about parsing a date with chronoparse. They could not be more different in shape:

A tutorial passage (learning-oriented): "Now let's parse our first date. In the file you just created, type exactly this and save it: result = chronoparse.parse("next Tuesday") Then add a line to see what came back: print(result) Run the file. You should see a real date printed to your screen—the date of the upcoming Tuesday. You just turned a phrase a human would type into a timestamp a computer can use. That's the whole idea of this library, and you just did it. Don't worry about what the other options do yet; we'll get there."

A reference passage (information-oriented), same topic: ```text chronoparse.parse(text, *, reference=None, tz=None, strict=False, locale="en_US")

text (str, required) The input string to parse. reference (datetime|None) The "now" to resolve relative dates against. Defaults to the current system time. tz (str|None) IANA time-zone name for the result. Default: naive. strict (bool) If True, raise ParseError on ambiguous input instead of guessing. Default: False. locale (str) Locale for month/day names. Default: "en_US".

Returns: datetime. Raises: ParseError (strict mode, unparseable input). ```

The tutorial passage is warm, narrated, encouraging, and ruthlessly narrow—one example, no options, an explicit emotional payoff ("you just did it"). The reference passage is cold, complete, alphabetized-by-nothing-but-utility, and useless to a beginner who would drown in reference, tz, strict, and locale before parsing a single date. Now imagine merging them—the fate of most real documentation. You'd get a "tutorial" that introduces the first parse and then, mid-stride, dumps the full parameter table on a reader who has no idea yet why any of it matters. The beginner stalls. The expert who actually wanted that table had to scroll past a hand-holding narrative to reach it. The merge degrades both. That is the core claim of Diátaxis, and once you see it you cannot unsee it: most bad docs aren't badly written; they're two or three good documents tangled into one bad one.

🧩 Productive Struggle. Before you read on, try sorting these five real documentation artifacts into the four quadrants. Don't peek—commit to an answer for each, because the act of deciding is what builds the instinct: (a) "Getting Started: Your First Query in 10 Minutes"; (b) the alphabetical list of every command-line flag the tool accepts; (c) "How to Migrate an Existing Database to v2"; (d) "Understanding the Trade-offs Between Our Caching Strategies"; (e) a page that opens "Welcome! This guide will introduce you to the tool, walk you through your first project, list all the configuration options, and explain our design philosophy."

Answer

(a) Tutorial — "your first," "in 10 minutes," learning-oriented; the reader is a beginner being carried to a first win. (b) Reference — a complete, lookup-oriented list; information, not instruction. (c) How-to guide — a specific task ("migrate an existing database"), assumes the reader already runs the tool; task-oriented. (d) Explanation — "understanding the trade-offs," theoretical, read away from the keyboard. (e) None of them—and that's the lesson. That opening promises all four modes in one document, which is the exact mixing-error Diátaxis exists to prevent. It will be too slow for the expert, too overwhelming for the beginner, and incomplete as a reference. The fix is not to rewrite that page but to split it into four pages, each doing one job.

The framework's practical payoff is a single diagnostic question you can ask of any page: What is the reader's situation—are they learning or working, and do they need to act or to know? Answer that, and the document's mode is fixed, and with it a hundred downstream decisions about scope, tone, and structure. This chapter focuses on the two practical, action-oriented quadrants on the left side of the grid—tutorial and how-to—because they share a surface (numbered steps, a reader at a keyboard) and are therefore confused constantly, and because getting their distinction right is the highest-leverage documentation skill a software writer can learn. (Reference you largely met in Chapter 25's API docs; explanation lives in the ADR and the design doc you'll see again in Chapter 34.)

[📍 Good stopping point — you now have the map. The rest of the chapter walks the two quadrants you'll use most.]

26.2 The Tutorial: Guaranteeing a Success Experience

A tutorial has one job that no other document shares: it must guarantee that the reader succeeds. Not "should probably work." Not "works if you have the right setup." Guaranteed. Because the reader of a tutorial is a beginner, and a beginner who fails doesn't conclude "I made a mistake"—they conclude "this tool is too hard, I'm not smart enough for this, I should use something else." A failed tutorial doesn't just fail to teach; it actively repels. The reader leaves with less confidence than they arrived with. So the entire craft of tutorial writing bends toward one outcome: a learner who reaches the end and thinks, I did it. That worked. I can do this. Everything else—what to include, what to cut, how much to explain—is subordinate to protecting that success.

This is what makes a tutorial fundamentally a teaching document, and teaching is the lens to write it through. You are not documenting a feature; you are choreographing a beginner's first experience so that it ends in a win. That reframing changes what "complete" means. A reference is complete when it covers everything. A tutorial is complete when it carries one reader, doing one concrete thing, all the way to a result—and it deliberately leaves out almost everything else, because every option you mention is a chance for the beginner to take a wrong turn.

Watch the difference between describing a feature and teaching a beginner to use it. Here is Raj's first instinct, when that frustrated issue asked for a tutorial—he wrote what he thought a tutorial was:

❌ Before — Raj's first attempt at a "tutorial" (it's actually a feature tour; fictional but realistic):

"chronoparse can parse a wide variety of date formats. To use it, call parse() with your input string. You can pass an optional reference argument to control what 'now' means for relative dates, a tz argument to set the time zone, and strict=True if you want it to raise an error on ambiguous input rather than making a best guess. The library also supports custom locales and can be extended with your own grammar rules for specialized formats. For batch processing, you may prefer parse_all(), which accepts an iterable and returns a generator. See the API reference for the full list of options."

Read it as a beginner. There is no first step. There is no concrete goal—no "by the end you will have done X." There is nothing to type, nothing to run, nothing to see. It's a list of capabilities aimed at someone who already knows what they're building, which is the description of a how-to or reference reader, not a learner. A beginner finishes this paragraph knowing slightly more about chronoparse and no more able to use it than before. It describes; it does not teach. Now here's the same opening, rebuilt as an actual tutorial:

✅ After — Raj's tutorial opening (learning-oriented):

"In this tutorial, you'll build a tiny script that reads a line of plain English—like 'meeting in 3 days'—and prints back a real calendar date. It takes about ten minutes, and by the end you'll have parsed your first date with chronoparse and seen exactly how it works. You don't need to know anything about date parsing. Just follow along and type what you see.

Step 1 — Create a file. Make a new file called firstdate.py and open it in your editor. (We'll add a few lines to it, run it, and watch what happens.)

Step 2 — Import the library and parse one phrase. Type exactly this into the file: import chronoparse result = chronoparse.parse("meeting in 3 days") print(result) Save the file.

Step 3 — Run it.* In your terminal, run python firstdate.py. You should see a date and time printed—three days from right now. That's it: you just turned a human sentence into a machine-readable date.* …"

Why it's better: It has a goal stated up front ("you'll build a script that…"), a time estimate that sets expectations, an explicit reassurance ("you don't need to know anything about date parsing"), a single concrete path with literal text to type, an instruction to save (the step experts forget—more on that in §26.5), a run step, an expected result so the reader can confirm success, and a named emotional payoff. It teaches one thing completely instead of mentioning ten things vaguely. The "After" version is, notice, less informative than the "Before" by raw feature count—and far more useful, because its job is not to inform but to carry a learner to a win.

The anatomy of a tutorial that works

From that contrast, the rules of a good tutorial fall out. Each one exists to protect the guaranteed success.

1. One concrete, visible goal, named up front. Not "learn about the library" but "build a script that prints a real date from a human sentence." The goal must be small enough to finish in one sitting and concrete enough that the reader knows, unambiguously, when they've succeeded. "Understand date parsing" has no finish line. "See a date printed to your screen" does. State it in the first paragraph so the reader knows where you're taking them.

2. A single, linear, tested path—no forks. A tutorial is a guided walk, not a map of the territory. The reader should never face a choice ("you can either do X or Y"), an option they must evaluate, or a branch they must navigate, because every decision point is a place a beginner can choose wrong and derail. Hide the options. There is exactly one way through, you've walked it, and it works. The competence to choose between approaches is what the how-to assumes—and the tutorial's reader doesn't have it yet. (This is the deepest structural difference between the two documents, and §26.4 returns to it.)

3. Everything the reader types, shown literally, with the result. Don't write "import the library and parse a date." Write the exact lines to type, then show what they should see when they run it. The expected output is not decoration—it's how the reader confirms they're on track. A beginner who types your code and sees the output you promised feels the click of success; a beginner who sees something different knows immediately that something's wrong, here, now, rather than discovering it three steps later when the cause is buried. Show the win at every checkpoint, not only at the end.

4. The minimum explanation, at the moment of use. A tutorial is not the place to explain how the grammar engine works or why relative dates are hard—that's explanation, a different quadrant. But a sentence of "here's what just happened" at the moment the reader sees a result turns rote copying into learning. The discipline is just enough: enough that the reader understands what they did, not so much that you've smuggled a design essay into a beginner's first ten minutes. When in doubt, say less and link to the explanation for the curious.

5. A guaranteed, tested environment. The fastest way to break the success guarantee is an environment assumption: the tutorial works on your machine, which has things installed and configured that the reader's doesn't. State the prerequisites explicitly and minimally at the very top ("You'll need Python 3.9+ and chronoparse installed—see Installation"), and—this is non-negotiable—run your own tutorial on a clean setup, exactly as Chapter 25 had you run your README's quick-start on a clean machine. The tutorial is only as reliable as the worst environment you tested it on.

6. A clear, satisfying ending. End on the win, name it, and tell the reader where to go next. "You've now parsed your first date. To handle time zones or batch files, see the how-to guides; to understand how the parser actually works, see [the explanation]." The ending closes the loop on the promise you made in the first paragraph and hands the now-confident beginner the next rung. A tutorial that just stops, with no "you did it" and no "here's what's next," wastes the momentum it worked so hard to build.

🔍 Why Does This Work? Why must a tutorial forbid choices that a how-to freely offers? A how-to guide can say "depending on your database, do A or B" because its reader is a competent practitioner who knows which database they have and can choose correctly. A tutorial's reader cannot—they're a beginner, by definition lacking the knowledge to evaluate the fork, and a wrong choice doesn't teach them a nuance; it dumps them into an error state they have no tools to escape, which breaks the success guarantee and sends the "I'm not smart enough for this" message. The forbidden fork isn't about dumbing down. It's about load: a beginner is already spending all their cognitive budget understanding the basics, with none left over to adjudicate options. The tutorial protects that budget by deciding for them. Once they've succeeded once, they have the foothold to start making choices—and that's when they graduate to how-to guides.

🔄 Check Your Understanding. A reader emails you about your tutorial: "Great walkthrough, but you should mention that step 5 also works with the --fast flag, and that experienced users might prefer the config-file approach instead of the command-line one." Should you take the suggestion and add both notes to the tutorial? Why or why not?

Answer

No—at least not in the tutorial. Both additions introduce choices ("you might prefer," "also works with") to a document whose entire job is to forbid choices and carry a beginner down one guaranteed path. The --fast flag and the config-file approach are real and useful, but they belong in a how-to guide ("How to speed up processing with --fast") or the reference (the full flag list), not in the learning-oriented tutorial. Adding them would help the experienced reader who emailed you and quietly harm the beginner the tutorial exists for, who would now face a fork they can't evaluate. The right response: thank them, and add the notes to the appropriate how-to or reference page. This is the mode-mixing error in miniature—a well-meant suggestion to make a tutorial more "complete" that would make it a worse tutorial.

26.3 The How-To Guide: Assuming Competence

If the tutorial's reader is a beginner you must carry, the how-to guide's reader is a competent practitioner you must respect—and respect, here, means get out of the way. The how-to reader already knows the basics. They've done the tutorial (or didn't need it). They have a specific, real problem right now—"I need to parse dates from a log file that uses a non-US locale and skip the lines that don't contain dates"—and they've come to your guide to solve that one problem and get back to their actual work. They do not want to be taught. They do not want encouragement. They want the recipe, accurate and complete, and then they want to be done.

This flips almost every tutorial rule on its head:

• A tutorial states a goal and guarantees it; a how-to assumes the reader can already do the basics and focuses entirely on the one new task.
• A tutorial forbids choices; a how-to offers them, because its reader can evaluate "if you're on Postgres, do this; if you're on MySQL, do that"—the choice is information the competent reader needs.
• A tutorial explains gently at the moment of use; a how-to explains almost nothing, because explanation slows down a reader who already understands and just wants the steps.
• A tutorial is a complete linear walk from zero; a how-to starts in the middle, assuming the reader has the tool installed and knows how to run it, and addresses only the specific task.
• A tutorial protects a fragile success; a how-to assumes a robust reader who can handle "if this fails, check your locale setting" without their confidence collapsing.

The defining test of a how-to is scope discipline: it solves exactly one problem. The title names a single task—"How to parse dates from a non-US locale," "How to process a whole file of dates," "How to handle ambiguous input strictly"—and the body solves precisely that, with no detours into adjacent topics. The moment a how-to tries to also be a gentle introduction, or also cover three related tasks, or also explain the design, it bloats into the same undifferentiated mess Diátaxis warns against. A good how-to is narrow on purpose.

Watch a how-to go wrong by reaching for tutorial habits, then get fixed:

❌ Before — a how-to that thinks it's a tutorial (fictional but realistic):

"## How to Process a File of Dates

Welcome! In this guide we'll learn how to use chronoparse to process a file. First, if you haven't already, you'll need to install chronoparse—open your terminal and run the install command, then create a Python file to work in. Date parsing can be tricky, so let's take it step by step. Start by importing the library, which we do at the top of any file that uses it. Now, a file is just a series of lines, and we want to parse each one. Don't worry if you're new to file handling—we'll go slowly. Open your file using Python's built-in open() function…"

The reader of this is a competent developer who came to solve "process a file of dates" and is now being taught what import does and reassured that file handling is okay. It's slow, it's condescending to its actual audience, and it buries the one thing they came for—how chronoparse applies to a file—under a beginner's onboarding they neither need nor wanted. Here's the same content as a how-to that respects its reader:

✅ After — a focused how-to (task-oriented):

"## How to Parse Every Date in a File

Goal: read a text file line by line and parse the date in each line, skipping lines with no date.

Prerequisites: chronoparse installed; you know how to run a Python script.

Use parse() inside a loop over the file's lines, and catch ParseError to skip lines without a parseable date:

python* *import chronoparse* *with open("events.txt") as f:* * for line in f:* * try:* * print(chronoparse.parse(line))* * except chronoparse.ParseError:* * continue # no date on this line; skip it* * For large files, use parse_all() instead, which returns a generator and skips unparseable lines for you: for dt in chronoparse.parse_all(open("events.txt")): print(dt)

Non-US dates? Pass locale= (e.g. locale='en_GB' for day/month order). See [How to handle locales]."

Why it's better: It names one task, states the goal and prerequisites in two lines and then trusts the reader, leads with the solution code immediately, offers a relevant choice (the parse_all() alternative for large files, which a competent reader can evaluate), handles the realistic failure case (skipping bad lines—the thing the reader actually came to figure out), and points to a sibling how-to for the adjacent locale problem instead of swallowing it. It's shorter, denser, and respects that its reader's time is the scarce resource (theme 6). No "welcome," no "don't worry," no teaching import.

⚠️ Warning — the most common how-to failure is the tutorial in disguise. Writers default to teaching mode because it feels generous. But a how-to padded with beginner hand-holding doesn't read as generous to its actual reader—it reads as an obstacle between them and the answer. If your how-to opens with "Welcome! In this tutorial we'll learn…," you've mislabeled the document and mis-served the reader. The tell: a competent reader has to scroll past things they already know to reach the part they came for.

🔄 Check Your Understanding. Same library, two readers. Reader A has never used chronoparse and never parsed a date in their life. Reader B uses chronoparse daily and needs to make it handle a Japanese-locale date file by this afternoon. For each, name the document type they need and the single biggest mistake you could make in writing for them.

Answer

Reader A needs a tutorial. The biggest mistake: offering choices or dumping the full option list, which overwhelms a beginner and breaks the success guarantee—plus assuming any setup they might not have. Carry them down one tested path to one win. Reader B needs a how-to ("How to parse dates in a non-US locale"). The biggest mistake: hand-holding—opening with "welcome, let's learn what a locale is," explaining import, or burying the locale= answer under a beginner's introduction. Respect that they're competent and lead with the recipe. Same library, same topic, opposite documents—because the reader's situation differs, which is theme 2 (audience is everything) wearing its Diátaxis uniform.

26.4 Why Mixing Modes Fails (and How to Tell Them Apart Fast)

We've now seen tutorial and how-to side by side, so we can state precisely why merging them—the thing nearly everyone does—produces bad documentation, and give you a fast field test to keep them separate.

The reason mixing fails is that the two documents optimize for opposite things, so any compromise between them is worse than either pole. A tutorial optimizes for a beginner's guaranteed success, which it buys by being narrow, slow, choice-free, and reassuring. A how-to optimizes for a competent reader's speed, which it buys by being dense, fast, choice-rich, and assumption-heavy. These aren't points on a single dial you can split the difference on; they're contradictory designs. A document halfway between them is too slow and hand-holding for the expert (who abandons it) and too dense and choice-laden for the beginner (who drowns in it). You can't serve both readers with one document for the same reason you can't write one paragraph that's simultaneously for the CEO and the engineer—Chapter 2's central lesson, now operating at the level of the whole document rather than the sentence. The finding is not the document; the reader's situation is.

There's a subtler failure too. When a document doesn't know what it is, the writer loses their decision rule. Every choice—include this option? explain this concept? add this caveat?—becomes a judgment call with no principle behind it, so the document accretes everything anyone ever thought to add, growing into the all-things-to-all-people sprawl that started this chapter. Naming the document's mode gives you back the decision rule: Does this serve my one reader's situation? In a tutorial, "include the full option list?"—no, it threatens the success path. In a reference, the same question—yes, completeness is the job. The mode decides. This is theme 1 (writing is thinking) at the level of document architecture: deciding what kind of document you're writing forces you to decide who it's for and what it must do, and that decision does most of the structural work for you.

Here is the fast field test. Faced with any document—one you're writing or one you're auditing—run these three questions:

If a single document gives tutorial answers to some questions and how-to answers to others, you've found a mode mix, and the fix is almost never to "balance" it—it's to split it into the two (or three, or four) documents it was trying to be, each clean. Splitting feels like more work and more files. It is less work for the reader, every time, which is the only ledger that counts.

❌ Before — one file trying to be three documents (excerpt; fictional but realistic): "# Using chronoparse / Welcome! This guide will get you started, show you how to handle every common scenario, and explain why we built it this way. Let's begin with your first parse… [carries a beginner through a first example]… Now that you've got the basics, here's how to handle time zones in production, how to batch-process files, and how to extend the grammar… [dense, choice-rich recipes]… It's worth understanding that under the hood, chronoparse uses a tokenizer feeding a grammar engine, which we chose over regex because… [a design essay]."

✅ After — split into three documents, each clean: - Tutorial: "Parse Your First Date in 10 Minutes" — beginner, one path, guaranteed win. (The first-example part.) - How-to guides: "How to Handle Time Zones," "How to Batch-Process a File," "How to Extend the Grammar" — each a focused recipe for one task. (The middle.) - Explanation: "Why chronoparse Uses a Grammar Engine, Not Regex" — understanding, read away from the keyboard. (The essay.)

Why it's better: Each reader now lands on a page built for exactly their situation and finds nothing in their way. The beginner gets carried; the practitioner gets recipes; the curious get the rationale. Same total content, three clean documents instead of one muddy one—and each is now findable, because its title names what it is, so a reader (or a search engine) can route straight to it. The split also makes each piece independently maintainable: you can fix the time-zone how-to without touching the tutorial.

🪞 Learning Check-In. Pause and turn the lens on your own writing. Think of the last set of instructions, docs, or onboarding material you wrote—at work, for a class, for a side project. Was it secretly trying to be two or three Diátaxis modes at once? Could the person who complained it was confusing (or who quietly gave up on it) have been a beginner drowning in a how-to, or an expert wading through a tutorial? You don't need to fix it now. Just notice whether the framework explains a frustration you'd previously chalked up to "I'm just bad at docs." Often the problem was never your prose—it was that the document didn't know what it was.

26.5 The Curse of Knowledge and the Assumed Step

Now we reach the chapter's most dangerous idea, the one that sinks more tutorials than bad prose ever could. You met it in Chapter 2 as the curse of knowledge—once you understand something, you can't easily imagine not understanding it—and in Chapter 22 as the reason you can't judge your own instructions. In a tutorial it takes a precise and deadly form: the assumed step.

An assumed step is an action so automatic to you that you've stopped experiencing it as an action. You don't decide to save the file before running it; your fingers hit save without a conscious thought. You don't remember to activate the virtual environment; it's muscle memory from a thousand mornings. You don't think "now I'll change into the project directory"; you're already there. So when you write the tutorial, you write the steps you're aware of performing and silently skip the ones that have sunk below awareness—and the beginner, who has none of your reflexes, stalls at exactly the gap you can't see. The most insidious thing about the assumed step is that re-reading your own tutorial won't reveal it. Your expert mind fills the gap automatically every time you read, supplying the missing save, the missing activation, the missing directory change, so the tutorial reads as complete to you no matter how many times you check. The gap is invisible from the inside. This is the curse of knowledge made specific and operational, and it is the number-one reason a tutorial that "works perfectly" for its author breaks for everyone else.

Here is what it looks like in the wild. This is the chapter's anchor case—Raj's getting-started tutorial, which he wrote, tested by re-reading three times, and shipped confidently. It worked for him every time. It broke for readers at step 4, and the cautionary tale (Case Study 1) traces the full forty-minute failure. The bug, reduced:

❌ Before — Raj's tutorial with a silent assumed step (the gap is at step 4):

"…Step 3 — Write your script. In analyze.py, type: import chronoparse from chronoparse import parse_all for dt in parse_all(open('events.txt')): print(dt)

Step 4 — Run it. Run python analyze.py. You should see a date printed for each line of your file."

Run it on Raj's machine and it works. Run it as a beginner who followed every word and you get:

FileNotFoundError: [Errno 2] No such file or directory: 'events.txt'

Step 4 promises a list of dates and delivers a crash—and the beginner has no idea why, because they did exactly what every step said. The assumed step is invisible in plain sight: the tutorial never told the reader to create events.txt. Raj had that file sitting in his project folder from testing; he opened it in the script without a thought, because for him it had always been there. It was never a step in his mind, so it never became a step on the page. The reader, with an empty folder, hits the gap and stalls—at step 4, with a cryptic error, exactly where a beginner is most likely to conclude "this is broken" or "I'm not cut out for this" and leave. Here is the fix:

✅ After — the assumed step made explicit (new Step 3, others renumbered):

"…Step 3 — Create a sample file to analyze. In the same folder, create a file called events.txt and put a few lines in it, like: text* *standup tomorrow at 9am* *launch in 2 weeks* *retro last Friday* * Save it. (This is the file your script will read.)

Step 4 — Write your script. In analyze.py, type: …

Step 5 — Run it. Run python analyze.py. You should see a date printed for each line — three dates, one per line above."

Why it's better: The missing action is now a numbered step, with the file's content shown literally so there's nothing to guess, an explicit save, a parenthetical that connects it to the next step ("this is the file your script will read"), and an expected result in step 5 that's now specific ("three dates, one per line") so the reader can confirm exact success. The gap is closed. Notice that the fix isn't better prose—Raj's sentences were fine. It's a missing step, and no amount of polishing the existing words would ever have surfaced it.

How to find the assumed step (because you can't see it by reading)

If re-reading can't reveal the gap, what can? Three techniques, in increasing order of reliability:

1. The literal step-by-step trace. Go through your own tutorial and, for every single step, ask: "What state must the world be in for this step to work, and did a previous step put it there?" For step 4 ("run the script that opens events.txt"), the required state is events.txt exists in this folder—and no previous step created it. The trace forces you to make the implicit prerequisites of each step explicit and check that each was actually established. It's tedious. It catches a lot. But it relies on you noticing your own assumptions, which the curse of knowledge specifically prevents, so it's necessary but not sufficient.

2. The fresh-environment run. Do the tutorial yourself, start to finish, on a clean setup—a new folder, a fresh virtual environment, a different machine, a container—doing only what the steps literally say and nothing your habits would add. This is Chapter 25's clean-machine test pointed at a tutorial, and it strips away the contaminating context (the leftover events.txt, the already-activated environment, the already-installed dependency) that your normal machine silently provides. The crash you hit on the clean run is the crash your reader will hit. This catches environmental assumed steps reliably.

3. The real beginner, watched silently. The gold standard, straight from Chapter 22: hand the tutorial to someone who has never done this task, ask them to follow it with no help from you, and watch without intervening. Every place they stall is a defect in the tutorial, not the tester. The beginner cannot fill the gap with expertise they don't have, so the assumed step that's invisible to you is a brick wall to them—and you finally get to see it. Bite your tongue when they stall; the instinct to "just tell them" destroys the data. The forty minutes of watching one person struggle will teach you more about your tutorial than forty re-readings ever could, because they lack precisely the knowledge whose curse blinds you.

🔄 Check Your Understanding. Why does re-reading your own tutorial reliably fail to catch an assumed step, no matter how carefully you read—and which of the three techniques above doesn't suffer from that flaw, and why?

Answer

Re-reading fails because your expert mind fills the gap automatically every time. When you read "run the script that opens events.txt," you don't notice the file was never created, because in your mind events.txt obviously exists—it's been on your machine and in your head the whole time. The curse of knowledge operates below awareness, so you can't introspect your way past it; reading harder just fills the gap harder. The fresh-environment run and the real-beginner test don't suffer from this, because they remove the source of the contamination from outside your head: the clean environment genuinely lacks events.txt (so the crash is real and visible), and the beginner genuinely lacks your knowledge (so they genuinely stall). You can't out-think your own curse of knowledge from the inside—you have to get the assumption out of your head and into the world, where its absence becomes observable.

26.6 Structuring Teaching Content: Worked Examples, Code Progression, and Screenshots

Beyond the tutorial-vs-how-to distinction, teaching through writing has a few structural techniques worth naming, because they recur across every learning-oriented document you'll ever write.

Worked examples and code progression

A worked example is a complete, runnable example you show in full, having walked the reader through building it, so they can see the whole working thing rather than fragments. Beginners learn powerfully from a complete example they can run, modify, and break—but only if they were carried to it, not dropped on it. The technique that carries them is code progression: you start with the smallest thing that works and add one capability at a time, showing the full code at each stage, so the reader's mental model grows by one increment per step instead of leaping.

Watch the difference. The wrong way drops the finished artifact on the reader:

❌ Before — the finished example, dumped whole: "Here's a script that reads a log file, parses the timestamp on each line, filters to the last 24 hours, and prints them sorted:" [followed by 30 lines of code doing all four things at once]

A beginner staring at 30 lines that do four things can't tell which lines do what, can't find where to start understanding, and certainly can't build it themselves. Now the progression:

✅ After — code progression, one capability at a time: "Stage 1 — parse one line. First, get a single date parsing. [3 lines; run it; see one date.] Works? Good. Stage 2 — read the file. Now wrap that in a loop over the file's lines. [add 2 lines; run it; see all dates.] Notice we only added the loop. Stage 3 — skip bad lines. Real logs have lines without dates, so catch the error and continue. [add the try/except; run it on a messy file; bad lines skipped.] Stage 4 — filter to recent. Finally, keep only the last 24 hours. [add the comparison; run it; only recent dates remain.] Here's the complete script:" [the full 30 lines, now understood, because the reader built every piece]

Why it's better: Each stage adds exactly one idea, shows the running result, and is independently verifiable—so a reader who breaks at stage 3 knows the bug is in the thing they just added, not buried somewhere in 30 lines. The full artifact arrives at the end as a summary of a journey the reader took, not a wall they have to scale. This is the single most effective structure for teaching anything procedural with code, and it generalizes: build the smallest working version, then grow it one verifiable increment at a time.

💡 Tip — the "happy path" first. In a tutorial, walk the happy path: the case where everything goes right, with no error handling, no edge cases, no defensive code. Get the reader to one clean success on the simplest possible version. Edge cases, failures, and robustness are real and important—but they belong in how-to guides ("How to handle malformed input") and reference, not in a beginner's first success experience, where they're noise that obscures the one idea you're teaching. Teach the happy path; defer the unhappy ones.

Annotated screenshots in teaching content

Tutorials for GUI tools, dashboards, and web interfaces often need screenshots—and the screenshot rules from Chapter 22 carry over directly, with one teaching-specific addition. The Chapter 22 discipline: crop to what matters, annotate the specific element with numbered callouts, and—critically—keep the text instruction authoritative, naming the element ("click the Deploy button in the top-right") so the instruction survives even if the image is stale, fails to load, or is read by a screen reader. Never write "click the button shown below" with no name, because a reader who can't see the image (slow connection, accessibility tool, a redesigned UI) is then stranded.

The teaching-specific addition is about what you screenshot in a tutorial versus a reference. In a tutorial, the most valuable screenshot is often the expected result, not the action—a picture of what success looks like so the beginner can compare their screen to yours and confirm they're on track. "After clicking Deploy, your dashboard should look like this:" followed by the success state is worth more to a learner than ten screenshots of buttons, because it answers the anxious beginner's constant question: did that work? A how-to or reference, by contrast, rarely needs result screenshots—its competent reader can tell whether it worked.

⚠️ Warning — screenshots rot. Every screenshot is a maintenance liability: UIs change, and a tutorial full of stale screenshots showing buttons that have moved or been renamed actively misleads beginners, who trust the picture over their own judgment. Screenshot only what genuinely needs showing (a non-obvious location, a success state), keep the named text instruction load-bearing so a stale image degrades gracefully, and write alt text describing the screenshot's content for readers who can't see it (accessibility, §9). A tutorial that depends on screenshots being current is a tutorial that quietly breaks every time the product ships.

✏️ Try This. Take a tutorial you've used recently—anything, for any tool. Find one screenshot in it and ask: if this image vanished, could I still follow the step from the text alone? If the answer is no (because the text says "click here" or "the button below" with no name), you've found the screenshot's hidden dependency—the kind that strands a reader the day the UI changes. Now ask the reverse: is there a place in that tutorial where a screenshot of the expected result would have reassured you, and wasn't there? Those two questions, asked of any tutorial, will sharpen your own screenshot judgment fast.

📐 Project Checkpoint

Your portfolio's user-documentation piece (piece 3) began life in Chapter 22 as a set of tested numbered instructions, and Chapter 25 surrounded your project with developer-facing docs—a README front door, perhaps an API reference. This chapter adds the document that teaches: a getting-started tutorial for that same project, the thing that takes a newcomer from "installed" to "I made it do something."

Write a tutorial, 400–800 words, that carries a complete beginner to one concrete, guaranteed success with your project (the tool, library, or process your user docs cover). Hold yourself to this chapter's anatomy:

1. State one concrete, visible goal in the first paragraph ("By the end, you'll have ___ and seen ___"), plus a time estimate and a reassurance that no prior knowledge is needed.
2. List minimal prerequisites at the top, then walk a single linear path—no forks, no "you could also," no options to evaluate.
3. Show everything the reader does literally (exact text to type or exact buttons to click, named), and after each meaningful step, show the expected result so they can confirm they're on track.
4. End on a named win and point to where they go next ("for ___, see the how-to guides").

Then—this is the part that matters most—find your assumed step. Run the literal step-by-step trace (§26.5): for each step, ask what state the world must be in and whether a prior step established it. Better, hand the tutorial to one person who has never done the task and watch them silently. The first place they stall is your assumed step; add the missing step and note what it was. A tutorial you haven't tested on someone else is a tutorial you only hope works.

In your portfolio, keep the tutorial next to but separate from your README and your how-to-style instructions—and label each by its Diátaxis type. That labeling is itself a portfolio signal: it shows a reviewer you understand that a project needs different documents for different readers, which is exactly the judgment Chapter 27 will extend when you start writing about data for audiences who range from a fellow analyst to a VP. Next chapter: Dana Whitfield's churn memo, written three ways—the long-promised payoff of the audience device from Chapter 2.

26.7 Common Mistakes and Practical Considerations

The mistakes in tutorial and how-to writing cluster tightly, because they nearly all trace back to two root causes: not knowing which Diátaxis mode you're in, and the curse of knowledge. Here are the ones practitioners make repeatedly.

Writing a feature tour and calling it a tutorial. The most common error: a "tutorial" that's actually a list of capabilities ("you can do X, you can also do Y") with no first step, no concrete goal, and nothing to run. Test: does your tutorial have a stated goal in paragraph one and a literal first action the reader performs? If not, it's a tour, and tours don't teach beginners.

The how-to that hand-holds. The mirror error: a how-to padded with "welcome," "don't worry," and explanations of basics its competent reader already knows, burying the answer they came for. Test: could your how-to reader find the actual recipe in the first few lines, or do they have to scroll past an onboarding they didn't need?

Offering choices in a tutorial. Every "you can either… or…" in a tutorial is a place a beginner can choose wrong and derail. Hide the options behind one tested path; relegate the alternatives to how-to guides. The tutorial decides for the reader, on purpose.

The unfixable assumed step. Shipping a tutorial you "tested" only by re-reading it. Re-reading cannot catch the assumed step (§26.5) because your mind fills the gap. The only reliable fixes are a fresh-environment run and a watched beginner. If you haven't done one of those, you don't know whether your tutorial works—you only know it works for you, which is precisely the wrong sample size of one.

Edge cases in the beginner's first success. Cramming error handling, configuration options, and "in production you'd want to…" caveats into a tutorial. They're real, but they're noise to a beginner chasing their first win. Teach the happy path; move the unhappy paths to how-to guides. (The exception: a safety warning that prevents real harm always goes in, before the dangerous step—Chapter 22's rule overrides happy-path simplicity when the stakes are physical or destructive.)

Stale screenshots that mislead. Tutorials that depend on screenshots being current break silently every time the UI changes, and beginners trust the stale picture over their own eyes. Keep the named text instruction authoritative; screenshot only what needs it; treat every screenshot as a maintenance debt.

Never deciding what the document is. The root error beneath all the others: sitting down to "write the docs" without deciding whether this page is a tutorial, a how-to, a reference, or an explanation. Without that decision you have no rule for what to include, and the document grows into the all-things-to-all-people sprawl that serves no one. Decide the mode first; let it make your inclusion decisions for you.

A few "it depends" notes for the real world. Not every project needs all four modes—a tiny tool might need only a README (with a quick-start) and a reference; a complex framework needs the full set. Add modes as the project's audience grows, not speculatively. The boundary between a thorough quick-start and a short tutorial is genuinely fuzzy—a README's quick-start (Chapter 25) is a miniature tutorial, and that's fine; the principle is the same (carry the reader to one success), only the length and prominence differ. How-to and reference sometimes live close together—a how-to may link heavily to reference for the exact options—and that's healthy as long as each stays in its lane (the how-to gives the recipe; the reference gives the complete option list). The framework is a tool for thinking, not a rigid taxonomy to enforce pedantically; its value is the decision rule it gives you, not bureaucratic purity about which quadrant a borderline page belongs to.

Frequently Asked Questions

What is the difference between a tutorial and a how-to guide?

A tutorial is learning-oriented: its reader is a beginner, and its job is to guarantee a success experience by carrying them down one tested path to a concrete win, hiding all choices and assuming no prior knowledge. A how-to guide is task-oriented: its reader is already competent and has a specific problem to solve, so it assumes the basics, offers relevant choices the reader can evaluate, and delivers the recipe for one task with minimal explanation. The one-sentence test: a tutorial guarantees success; a how-to assumes it. They share a surface (numbered steps) but optimize for opposite things—a beginner's guaranteed success versus a practitioner's speed—which is why merging them produces a document that serves neither.

What is the Diátaxis framework?

Diátaxis (by Daniele Procida) is a framework that sorts technical documentation into four distinct types along two axes—whether the reader is studying or working, and whether they need practical action or theoretical understanding. The four are: tutorial (study + practical, learning-oriented), how-to guide (work + practical, task-oriented), reference (work + theoretical, information-oriented), and explanation (study + theoretical, understanding-oriented). Its central claim is that each type has a different reader and purpose, so a document trying to be two types at once serves neither well—and most confusing documentation is several good documents tangled into one bad one.

Why does so much software documentation feel confusing?

Usually because it's mixing Diátaxis modes—trying to be a tutorial, a how-to, a reference, and an explanation all in one page. That makes it simultaneously too slow and hand-holding for the expert (who abandons it) and too dense and choice-laden for the beginner (who drowns). The prose may be perfectly good; the architecture is broken, because the document never decided what it was or who it was for. The fix is rarely to rewrite the prose—it's to split the page into separate documents, each serving one reader's situation cleanly.

What is an "assumed step" and how do I find it?

An assumed step is an action so automatic to you—save the file, activate the environment, create the sample file, change directories—that you've stopped noticing it as an action, so you leave it out of your tutorial, and a beginner stalls at exactly the gap. It's the curse of knowledge in operational form. You cannot find it by re-reading, because your expert mind fills the gap automatically every time. You find it by getting the assumption out of your head and into the world: run the tutorial on a clean, fresh environment that genuinely lacks your context, or—best—hand it to a real beginner and watch them silently. The first place they stall is your assumed step.

Should a tutorial include error handling and edge cases?

No—keep them out of the tutorial. A tutorial teaches the happy path: the simplest case where everything goes right, so the beginner reaches one clean success without noise. Error handling, configuration options, and edge cases are real and important, but they belong in how-to guides ("How to handle malformed input") and reference, where a competent reader can use them. The one exception: a safety warning that prevents real harm always goes in, before the dangerous step (Chapter 22's rule). Otherwise, teach the happy path and defer the unhappy ones.

Chapter Summary

Key Takeaways

• Technical documentation isn't one thing—it's four (Diátaxis): tutorial (learning-oriented), how-to (task-oriented), reference (information-oriented), explanation (understanding-oriented). Each has a different reader and purpose; mixing them in one document degrades all of them.
• A tutorial guarantees success; a how-to assumes it. That single sentence sorts nearly every decision about scope, tone, and choices.
• A tutorial is learning-oriented: one concrete goal stated up front, a single tested path with no forks, everything shown literally with the expected result, minimal explanation at the moment of use, a guaranteed clean environment, and a named win at the end.
• A how-to is task-oriented: it assumes competence, solves exactly one problem, offers relevant choices the reader can evaluate, explains almost nothing, starts in the middle, and respects the reader's time.
• The assumed step—an action you do automatically and forget to write—is the curse of knowledge made specific, and it sinks tutorials. You can't catch it by re-reading; only a fresh-environment run or a watched beginner reveals it.
• Teach with code progression (smallest working version, then one verifiable increment at a time) and worked examples; show the expected result, not just the action.

Action Items

• Before writing any documentation page, decide its Diátaxis mode and write it at the top of your draft. Let the mode make your inclusion decisions.
• For any tutorial, run the literal step-by-step trace and then a fresh-environment run; ideally, watch one real beginner attempt it with no help.
• Audit one existing "doc" you own for mode-mixing; if it's two or three documents in one, split it.
• For how-to guides, cut every "welcome," "don't worry," and explanation of basics; lead with the recipe.

Common Mistakes

• A feature tour mislabeled as a tutorial (no goal, no first step, nothing to run).
• A how-to that hand-holds and buries the answer under a beginner's onboarding.
• Choices offered inside a tutorial (each is a place a beginner derails).
• Shipping a tutorial "tested" only by re-reading (the assumed step survives).
• Edge cases and error handling crammed into a beginner's first success.

Decision Framework — Which document am I writing?

The fast field test: Is the reader learning or working? Do they need to act or to know? Those two questions fix the mode—and the mode does most of the structural work for you.

Spaced Review

A few questions reaching back, to strengthen retention.

1. (From Chapter 24) The canonical lesson of code documentation is "comment the why, not the what." How does that lesson connect to Diátaxis—specifically, which of the four documentation modes is the natural home for "the why" of a whole design decision?
2. (From Chapter 22) Chapter 22's diagnostic was "the someone-who-has-never-done-this test," and this chapter leaned on it again to find the assumed step. State, in one sentence, why the author of a tutorial is the worst possible judge of whether it works.
3. (From Chapter 25, bridging) Chapter 25 measured a README by time-to-first-success and tested it on a clean machine. How are those two ideas the direct ancestors of this chapter's "guarantee a success experience" and "fresh-environment run"?

What's Next

You've now written the documents that teach a reader to use a tool. Chapter 27 turns to a different and trickier teaching problem: writing about data—a churn analysis, a dashboard, an analysis memo—where the thing you're explaining isn't a tool the reader operates but a finding they must understand and act on, and where the audience swings from a fellow analyst to a VP who has three minutes and one question: "so what should we do?" You'll finally see Dana Whitfield's churn memo written three ways—methodology-first, findings-first, recommendation-first—the long-promised payoff of the audience device introduced way back in Chapter 2. The Diátaxis instinct you just built (different reader, different document) is exactly the muscle you'll use, now pointed at numbers instead of code.

Practice: Exercises · Quiz Go deeper: Case Study · Case Study 2 Review: Key Takeaways · Further Reading