Quiz — Chapter 26: Technical Tutorials and How-To Content

Target: 70%+ before moving on.

Section 1 — Multiple Choice

1. The single sentence that best distinguishes the two practical documentation modes is:

  • A) A tutorial is short; a how-to is long.
  • B) A tutorial guarantees success; a how-to assumes it.
  • C) A tutorial uses screenshots; a how-to uses code.
  • D) A tutorial is for software; a how-to is for hardware.
Answer**B.** The defining difference is the reader's situation and the document's promise: a tutorial's reader is a beginner whose success the document must *guarantee*; a how-to's reader is competent, so it *assumes* they can already do the basics. Length (A), media (C), and subject (D) are incidental—a tutorial can be long, use code, and cover hardware. (§26.2, threshold concept.)

2. The Diátaxis framework organizes documentation along two axes. They are:

  • A) Short vs. long, and beginner vs. expert.
  • B) Study vs. work, and practical vs. theoretical.
  • C) Internal vs. external, and free vs. paid.
  • D) Text vs. video, and online vs. print.
Answer**B.** The axes are whether the reader is *studying* (learning) or *working* (applying skill), and whether they need *practical* action or *theoretical* understanding. Crossing them yields tutorial, how-to, reference, and explanation. (§26.1.)

3. A page opens: "Welcome! This guide will get you started, show you how to handle every scenario, list all the options, and explain our design philosophy." The core problem is:

  • A) The tone is too informal.
  • B) It's too short.
  • C) It promises all four Diátaxis modes in one document, so it will serve none of them well.
  • D) It doesn't have enough screenshots.
Answer**C.** "Get you started" (tutorial), "handle every scenario" (how-to), "list all options" (reference), "explain philosophy" (explanation) are four different documents promised in one. It will be too slow for the expert and too overwhelming for the beginner. The fix is to *split* it, not to adjust tone (A) or add screenshots (D). (§26.1, §26.4.)

4. In a tutorial, you should:

  • A) Offer the reader several ways to accomplish each step so they can pick their favorite.
  • B) Walk a single tested path with no forks, hiding the alternatives.
  • C) List every configuration option up front so the reader knows what's available.
  • D) Start with error handling so the reader is prepared for failures.
Answer**B.** A tutorial forbids choices, because every fork is a place a beginner can choose wrong and derail, breaking the guaranteed success. Options (A), full option lists (C), and error handling (D) all belong in how-to guides or reference—the tutorial walks one path to one win. (§26.2.)

5. The "assumed step" is best described as:

  • A) A step the reader is assumed to skip.
  • B) An action the author performs so automatically they forget to write it, so a beginner stalls at the gap.
  • C) An optional step that advanced users can ignore.
  • D) The first step of any tutorial.
Answer**B.** The assumed step is the curse of knowledge made operational: save the file, activate the environment, create the sample file—actions so automatic to the expert that they've sunk below awareness and never make it onto the page. The beginner, lacking the reflex, stalls exactly there. (§26.5.)

6. Why does re-reading your own tutorial fail to catch an assumed step?

  • A) Because tutorials are too long to read carefully.
  • B) Because your expert mind fills the gap automatically every time you read it.
  • C) Because the assumed step is always at the end.
  • D) Because re-reading is boring and you skim.
Answer**B.** The curse of knowledge operates below awareness, so when you read "run the script that opens `events.txt`," your mind supplies the file's existence automatically—you literally cannot see the gap from inside your own expertise. Reading harder fills the gap harder. Only a clean environment or a real beginner, which lack your context from *outside* your head, reveal it. (§26.5.)

7. A how-to guide should solve:

  • A) As many related tasks as possible, for efficiency.
  • B) Exactly one problem named in the title.
  • C) Whatever the beginner needs explained.
  • D) The whole product, comprehensively.
Answer**B.** Scope discipline is the defining test of a how-to: the title names one task and the body solves precisely that, with no detours. Trying to cover many tasks (A, D) bloats it into the mode-mixed sprawl Diátaxis warns against; explaining basics to a beginner (C) is the tutorial's job. (§26.3.)

8. The recommended structure for teaching procedural content with code is:

  • A) Show the complete finished example first, then explain each line.
  • B) Code progression—start with the smallest working version and add one verifiable capability at a time.
  • C) Show only fragments and let the reader assemble them.
  • D) Provide the reference documentation and let the reader figure it out.
Answer**B.** Code progression grows the reader's mental model one increment per step, each independently runnable and verifiable, so a reader who breaks at stage 3 knows the bug is in what they just added. The complete artifact arrives at the *end*, as the summary of a journey—not dumped at the start (A), which leaves a beginner unable to tell which lines do what. (§26.6.)

9. In a tutorial, the most valuable kind of screenshot is often:

  • A) A screenshot of every button the reader might click.
  • B) A screenshot of the expected result, so the beginner can confirm they're on track.
  • C) A decorative banner image.
  • D) A screenshot of the source code.
Answer**B.** A picture of *what success looks like* answers the anxious beginner's constant question—"did that work?"—and lets them compare their screen to yours. A how-to's competent reader rarely needs result screenshots; this is a teaching-specific addition. (Action screenshots still follow [Chapter 22](../../part-04-professional-workplace-writing/chapter-22-instructions-procedures/index.md)'s rules: crop, name the element, keep text authoritative.) (§26.6.)

10. Which item correctly pairs a topic with its Diátaxis mode?

  • A) "Why we chose a grammar engine over regex" → tutorial.
  • B) The alphabetical list of every command-line flag → reference.
  • C) "Parse your first date in 10 minutes" → reference.
  • D) "How to migrate to v2" → explanation.
Answer**B.** A complete, lookup-oriented list is reference. The others are mismatched: "why we chose…" is *explanation* (not tutorial); "your first… in 10 minutes" is a *tutorial* (not reference); "how to migrate…" is a *how-to* (not explanation). (§26.1.)

11. Edge cases and error handling in a tutorial should generally be:

  • A) Front-loaded, so the beginner is ready for problems.
  • B) Left out—teach the happy path; defer edge cases to how-to guides—with the exception of a genuine safety warning.
  • C) Covered exhaustively, since completeness is a tutorial's goal.
  • D) Replaced entirely with a link to the source code.
Answer**B.** A tutorial teaches the happy path so the beginner reaches one clean success without noise; edge cases belong in how-tos and reference. The one override: a *safety/destructive* warning always goes in, before the dangerous step ([Chapter 22](../../part-04-professional-workplace-writing/chapter-22-instructions-procedures/index.md)'s rule). Completeness (C) is reference's job, not a tutorial's. (§26.6, §26.7.)

12. The fast field test for deciding a document's mode is:

  • A) How long should it be, and how many screenshots?
  • B) Is the reader learning or working, and do they need to act or to know?
  • C) Is it internal or external, and who approved it?
  • D) Is it for the website or the repo?
Answer**B.** Those two questions fix the quadrant: learning + act = tutorial; working + act = how-to; working + know = reference; learning + know = explanation. The mode then makes most downstream structural decisions for you. (§26.1, Decision Framework.)

Section 2 — True/False with Justification

State true or false and justify in one sentence.

T1. A document with numbered steps is necessarily a tutorial.

Answer**False.** How-to guides, SOPs ([Chapter 22](../../part-04-professional-workplace-writing/chapter-22-instructions-procedures/index.md)), and README quick-starts ([Chapter 25](../chapter-25-readme-api-docs/index.md)) all use numbered steps; the steps are a shared surface. What makes a document a tutorial is its *reader* (a beginner) and its *promise* (guaranteed success), not its formatting.

T2. Offering the reader a choice between two approaches is good practice in a how-to guide but bad practice in a tutorial.

Answer**True.** A how-to's competent reader can evaluate "if Postgres, do A; if MySQL, do B"—the choice is information they need. A tutorial's beginner cannot evaluate the fork and may choose wrong and derail, breaking the success guarantee, so tutorials hide options.

T3. If a tutorial works perfectly every time the author runs it, it's ready to ship.

Answer**False.** "Works for the author" is exactly the failure mode—the author's machine and mind silently supply the assumed steps (the leftover file, the activated environment). It's ready only after a fresh-environment run or a watched beginner confirms it works *without* the author's context.

T4. Splitting one mixed document into several single-mode documents is more work and therefore worse.

Answer**False.** It may be marginally more work for the *writer* (more files), but it's less work for every *reader*, who now lands on a page built for their exact situation with nothing in the way—and the reader's time is the ledger that counts.

T5. The rationale for a design decision (the "why") belongs in a tutorial.

Answer**False.** The "why"—rationale, trade-offs, background—is *explanation* (understanding-oriented), read away from the keyboard; the Architecture Decision Record from [Chapter 25](../chapter-25-readme-api-docs/index.md) is its natural home. A beginner's tutorial needs just enough explanation to understand what they did, not a design essay.

T6. A README's quick-start and a standalone tutorial are governed by completely different principles.

Answer**False.** They share the same principle—carry the reader to one working success—and the boundary between them is genuinely fuzzy; a quick-start is essentially a miniature tutorial. They differ in length and prominence, not in their core discipline.

Section 3 — Short Answer

S1. In two or three sentences, explain why mixing a tutorial and a how-to into one document produces a worse result than either pure document.

Model answerThe two optimize for opposite things—a tutorial for a beginner's guaranteed success (narrow, slow, choice-free), a how-to for a competent reader's speed (dense, fast, choice-rich)—so any compromise is too slow and hand-holding for the expert and too dense and choice-laden for the beginner. They aren't points on one dial you can split; they're contradictory designs, so the midpoint serves neither reader. *Rubric: names the opposing optimizations and that the midpoint fails both.*

S2. Name the three techniques for finding an assumed step, in order of reliability, and state why re-reading isn't one of them.

Model answer(1) The literal step-by-step trace (ask what state each step requires and whether a prior step established it); (2) the fresh-environment run (do the tutorial on a clean setup that lacks your context); (3) the watched beginner (hand it to someone who's never done it and watch silently). Re-reading fails because the curse of knowledge makes your mind fill the gap automatically every time. *Rubric: all three named in roughly that order + the curse-of-knowledge reason.*

S3. A colleague says, "Our 'User Guide' covers absolutely everything in one document, so users never have to look in multiple places." Reframe this using Diátaxis: is it a strength or a symptom?

Model answerIt's a symptom of mode-mixing, not a strength. "Everything in one place" means a beginner, an expert, a fact-checker, and a curious reader all land on the same page, where each must wade through three modes' worth of content meant for the other three readers. "Never look in multiple places" is the problem restated as a virtue—readers *want* a page built for their situation, which means several findable documents, not one comprehensive one. *Rubric: identifies mixing + that single-page comprehensiveness harms each reader.*

S4. Why is the author of a tutorial the worst possible judge of whether it works? Connect it to a prior chapter.

Model answerBecause of the curse of knowledge ([Chapter 2](../../part-01-writing-is-thinking/chapter-02-audience/index.md)): once you understand something you can't imagine not understanding it, so the author's mind fills every gap—the assumed step, the undefined term—automatically, making the tutorial read as complete no matter how carefully they check. This is the same reason [Chapter 22](../../part-04-professional-workplace-writing/chapter-22-instructions-procedures/index.md) insisted you watch a real beginner try your instructions: the author's expertise is the contamination, so only a reader who lacks that expertise can reveal the gaps. *Rubric: names curse of knowledge + the [Ch 2](../../part-01-writing-is-thinking/chapter-02-audience/index.md) or [Ch 22](../../part-04-professional-workplace-writing/chapter-22-instructions-procedures/index.md) link.*

S5. Give one example each of the same topic ("creating a user account") as it would appear in a tutorial versus a how-to. One sentence each.

Model answer**Tutorial:** "In this tutorial you'll create your very first user account and log in as them—about five minutes; just follow along," then a single literal path to one account with the result shown. **How-to:** "How to bulk-create users from a CSV"—a specific task for a competent admin, leading with the command and the file format, offering the dry-run flag as a choice. *Rubric: tutorial = beginner/one path/guaranteed; how-to = one specific task/assumes competence.*

Section 4 — Applied Scenario

Scenario. You are handed this "tutorial" excerpt to fix. It was reported as confusing by new users.

"## Getting Started with DeployBot. DeployBot supports many deployment targets including AWS, GCP, Azure, and bare-metal servers, and can be configured via CLI flags, a YAML file, or environment variables. To begin, choose your preferred configuration method and target, then run the deploy command with the appropriate options for your environment. You may also want to set up a CI integration. For production use, consult the security hardening guide. Once deployed, verify your service is reachable."

Write a short critique (4–6 sentences) and then rewrite just the opening and first two steps as a real tutorial. Your critique should name (a) which Diátaxis mode this claims to be, (b) what it actually is, (c) the forks that will derail a beginner, and (d) the missing concrete goal. Your rewrite should pick one target and one config method (hide the rest), state a concrete goal with a time estimate, and give two literal steps with an expected result.

Rubric **Critique (full marks):** identifies it claims to be a tutorial ("Getting Started"); is actually a feature tour / how-to hybrid (lists capabilities, assumes the reader can "choose," no first action); names the forks ("choose your preferred method and target," "you may also want," "for production consult…") as derailment points for a beginner who can't evaluate them; notes there's no concrete goal and nothing to run. **Rewrite (full marks):** picks one target and one config method and *commits* to it (no "choose"); states a concrete, finishable goal in paragraph one ("By the end you'll have deployed a sample app to [one target] and seen it live") with a time estimate; gives two literal steps with exact commands/actions; shows an expected result after a step so the reader can confirm success; defers AWS/GCP/Azure/CI/security to "see the how-to guides." Bonus: no "you may also want," no options, warm but lean tone.

Scoring & Next Steps

Score What to do
< 50% Re-read §26.1 (Diátaxis) and §26.2–§26.3 (tutorial vs. how-to). The two are confused because they share a surface—focus on reader and promise, not formatting.
50–70% Redo Part B (Revise This) in the exercises, especially B1–B3; the tutorial/how-to distinction lives in the editing, not the theory.
70–85% You've got it. Proceed to Chapter 27—and apply the "which mode / which reader" instinct to your own project's docs.
> 85% Try Part E (Extension): map a real project's full Diátaxis structure (E1) or audit a published tutorial for assumed steps on a clean machine (E3).