Key Takeaways — Chapter 26: Technical Tutorials and How-To Content

A one-page summary card. Use it to re-ground before the quiz, or to review weeks later.

The one idea

A tutorial guarantees success; a how-to assumes it. That single sentence sorts almost every decision you'll make about a piece of teaching content—what to include, what to cut, whether to offer choices or forbid them, what tone to take. The two documents share a surface (numbered steps, a reader at a keyboard) and so get blurred together constantly, but they serve opposite readers: a tutorial carries a beginner down one tested path to a guaranteed win; a how-to hands a competent practitioner the recipe for one task and gets out of the way.

🚪 Threshold concept: A tutorial is learning-oriented—its job is not to describe a feature but to guarantee a beginner's success experience, because a beginner who fails concludes "I'm not smart enough for this" and leaves. Cross this threshold and your priorities flip: you stop optimizing for completeness (covering everything) and start optimizing for the learner reaching one clean win. The full option list, the edge cases, the design rationale—all the things that make a document "thorough"—come out of the tutorial, because each is a place a beginner can derail.

The framework: Diátaxis (the four kinds of documentation)

Documentation isn't one thing—it's four (Daniele Procida, Tier 1), sorted by two questions: is the reader studying or working? and do they need to act or to know?

Mixing modes is the silent cause of most bad docs. A page trying to be a tutorial and a how-to and a reference is too slow for the expert and too overwhelming for the beginner. The fix is rarely better prose—it's to split the page into single-mode documents, each built for one reader's situation. Most "confusing documentation" is several good documents tangled into one bad one.

The core moves

• Tutorial: one concrete goal up front; a single tested path with no forks; everything shown literally with the expected result after each step; minimal explanation at the moment of use; a guaranteed clean environment; a named win at the end. Walk the happy path—defer edge cases to how-tos.
• How-to: assume competence; solve exactly one problem named in the title; offer the relevant choices a competent reader can evaluate; explain almost nothing; start in the middle; respect the reader's time. No "welcome," no hand-holding.
• Teach with code progression: smallest working version first, then one verifiable increment at a time; the full artifact arrives at the end, as the summary of a journey the reader took.
• Screenshots: crop, name the element in text (so a stale image degrades gracefully—Chapter 22), and in a tutorial, screenshot the expected result so the beginner can confirm "did that work?"

The diagnostic

The assumed step. The curse of knowledge (Chapter 2) in operational form: an action you do so automatically—save the file, activate the environment, create the sample file—that you forget to write it, and a beginner stalls at the gap. You cannot catch it by re-reading, because your expert mind fills the gap every time. Only a fresh-environment run (Chapter 25's clean-machine test, pointed at a tutorial) or a watched beginner (Chapter 22's "someone who has never done this" test) reveals it. The author is the worst judge of their own tutorial.

The test to apply before you ship any teaching content

First: do I know what this document is—tutorial, how-to, reference, or explanation? Then: if it's a tutorial, has someone who has never done this (or I, in a brand-new empty environment) followed it to the promised success, with no help and nothing I already had lying around?

If you can't name the mode, the document doesn't know what it is and will confuse someone. If you haven't tested the tutorial on a fresh environment or a real beginner, you don't know whether it works—you only know it works for you, which is the wrong sample size of one.

Themes this chapter surfaced: #2 audience-is-everything (the audience is a learner in a tutorial, a practitioner in a how-to—same topic, opposite documents) · #1 writing-is-thinking (deciding what kind of document you're writing forces you to decide who it's for and what it must do, which does most of the structural work) · #5 structure-serves-the-reader (the mode dictates the structure; the reader's situation, not your knowledge, sets the order) · #6 every-sentence-earns-its-place (cut the hand-holding from how-tos and the option-lists from tutorials).

Threshold concept: A tutorial guarantees success; a how-to assumes it.

Back to: Chapter 26 · Exercises · Quiz · Further Reading