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

Writing is learned by writing. These exercises ask you to classify, diagnose, and produce real teaching documents—not to pick letters. Where a task is open-ended, a self-assessment rubric follows instead of a single answer.

Selected solutions and rubrics: appendices/answers-to-selected.md.

Part A — Analyze This ⭐

A1. Classify these docs by Diátaxis type. For each title or opening line, name the type (tutorial, how-to, reference, or explanation) and give the one-clause reason (who's the reader / what's the promise):

1. "Build Your First Dashboard in 15 Minutes"
2. "Configuration Options" — an alphabetical table of every setting, its type, and its default
3. "How to Roll Back a Failed Migration"
4. "Why We Chose Event Sourcing Over a Traditional CRUD Database"
5. "Getting Started: Send Your First API Request"
6. "API Reference: POST /v1/messages" — the endpoint's request fields, response shape, and error codes
7. "Understanding Eventual Consistency"
8. "How to Connect the App to a Postgres Database"

A2. Here is the opening of a page titled "Using the Reporting Tool." Read it as each of two readers, then answer:

"Welcome! This guide will get you up and running, walk you through building your first report, cover every export format we support, and explain the philosophy behind our query language. Let's begin…"

(a) Name every Diátaxis mode this single page is promising. (b) Why will this page frustrate a complete beginner? (c) Why will it frustrate an expert who just wants the list of export formats? (d) What's the fix—and is it "rewrite" or "restructure"?

A3. A tutorial step reads: "Step 6 — Deploy your app by clicking the button in the corner." Name two distinct things wrong with this step (hint: one is a Chapter 22 screenshot/instruction problem, one is a clarity problem), and rewrite it.

A4. Tutorial or how-to? Below is a passage. Decide which type it's trying to be, then decide which type it actually reads as, and explain the mismatch:

"## How to Batch-Process Files. New to batch processing? No problem! A batch is just a group of files. Don't worry if you've never done this before. First, let's make sure you understand what a loop is. A loop repeats an action…"

A5. Identify the assumed step. This three-step tutorial works on the author's machine and crashes for everyone else:

"Step 1 — Open your terminal. Step 2 — Run python report.py. Step 3 — Open report.pdf to see your output."

The reader gets python: can't open file 'report.py': [Errno 2] No such file or directory. What action did the author do automatically and forget to write? Where should the missing step go?

A6. A how-to guide for configuring HTTPS opens with three paragraphs explaining what TLS is, why encryption matters, and the history of SSL. Its reader is a sysadmin who needs to turn on HTTPS this afternoon. What's wrong, and what should those three paragraphs become (where do they belong)?

A7. Find the assumed step in this longer tutorial excerpt (the reader did everything literally and step 4 fails):

"Step 1 — Create app.py. Step 2 — Paste the starter code below. Step 3 — Install the dependencies. Step 4 — Run flask run; open http://localhost:5000 to see your app."

The reader sees Error: Could not locate a Flask application. Two plausible assumed steps could cause this depending on the setup—name at least one, and explain why re-reading wouldn't have caught it.

Part B — Revise This ⭐⭐

B1. This "tutorial" is actually a feature tour. Rewrite its opening (the first ~150 words) into a real tutorial opening: state one concrete goal, give a time estimate, reassure the beginner, and write Step 1 as a literal action with an expected result.

"PixelResize is a flexible image-processing library. You can resize images by width, height, or percentage; convert between formats; apply filters; and process whole directories in batch. It supports a configuration file for repeated workflows and exposes a low-level API for custom pipelines. To get started, install it and explore the options that fit your use case."

B2. This how-to hand-holds its competent reader. Rewrite it to assume competence: cut the onboarding, lead with the recipe, keep only what a practitioner needs.

"## How to Export to CSV. Welcome to the export guide! Exporting is a great way to share your data. Don't worry, it's easy. First, you'll need to have some data in the tool—if you don't, go back and create a report first. Got data? Great. Now, a CSV is a simple text format that spreadsheets can open. To make one, look for the Export menu, which is usually near the top of the screen, and you'll want to click on it, and then you should see some options, and one of them will say CSV…"

B3. This tutorial offers a fork that will derail beginners. Rewrite it to walk one tested path and relocate the alternative.

"Step 3 — Save your work. You can either use the keyboard shortcut, or click File then Save, or if you prefer you can set up auto-save in the preferences, or use the command palette—whichever you're most comfortable with. Once it's saved, continue to step 4."

B4. This tutorial drops a finished 4-job script on the beginner. Restructure it as a code progression: describe (in prose, you don't need to write real code) the four stages, each adding one capability with a verifiable result, and where the full script goes.

"Here's a complete script that connects to the database, runs a query, formats the results as a table, and emails the table to a list of recipients:" [25 lines doing all four]

B5. This tutorial ending just stops. Rewrite the ending to (a) name the win, (b) close the loop on the goal promised at the start ("build a script that prints a real date"), and (c) point the now-confident beginner to where they go next.

"…and the date prints to your terminal. Step 7 is the last step."

B6. A teammate's how-to tries to cover three tasks ("How to Import, Export, and Sync Your Data") in one document, and readers keep saying it's confusing. Don't rewrite the prose—describe the restructuring: what becomes how many documents, what each is titled, and why this serves readers better than one combined guide.

Part C — Write This ⭐⭐–⭐⭐⭐

C1. Write a tutorial. Pick something you can genuinely do in under 15 minutes and that a beginner couldn't (examples: "send your first email with a CLI tool," "create your first chart in a spreadsheet from raw numbers," "make your first commit with git"). Write a complete tutorial (~400–600 words) that meets the chapter's anatomy: one concrete goal stated up front, a time estimate, a reassurance, minimal prerequisites, a single linear path with literal actions, an expected result after each meaningful step, and a named win at the end with a "what's next" pointer. Then test it on one real beginner and note, in a sentence, the first place they stalled (your assumed step).

C2. Write a how-to for the same topic. Take the same tool you used in C1 and write a how-to guide (~150–250 words) for a specific, different task aimed at a competent user (e.g., if C1 was "your first git commit," C2 might be "How to undo your last commit without losing your changes"). Assume competence: state the goal and prerequisites in one line each, lead with the recipe, offer a relevant choice if one exists, explain almost nothing. Put C1 and C2 side by side and confirm they read as genuinely different documents.

C3. Diagnose and split. Find a real piece of documentation online (any tool you use) that mixes Diátaxis modes. Write a short (~250-word) "documentation triage": name what modes are tangled in it, identify one beginner it fails and one expert it fails, and propose the split—how many documents it should become and what each would be titled.

C4. Write the "expected result" passages. For a tutorial of your choice, write three "checkpoint" passages—the kind that show a beginner what success looks like after a step ("After running this, you should see…"). Make each specific enough that a reader could confirm they're on track and would notice immediately if something went wrong.

Part D — Synthesis & Critical Thinking ⭐⭐⭐

D1. The same content, four ways. Pick one narrow topic in a tool you know (e.g., "parsing a date," "creating a user," "deploying a build"). In 2–3 sentences each, sketch how that one topic appears in all four Diátaxis modes: as a tutorial passage, a how-to recipe, a reference entry, and an explanation. The point is to feel how different the same topic looks depending on the reader's situation.

D2. Translate for audience (cross-chapter, Ch 2). Chapter 2 had you write one finding for four readers; this is the documentation version. Take the instruction "to handle ambiguous dates, the library can run in strict mode" and write it three ways: (a) inside a tutorial (does it even belong there? decide), (b) inside a how-to ("How to reject ambiguous input"), (c) inside the reference (the strict parameter entry). Then explain in one sentence why the tutorial version was the hard call.

D3. Find the flaw. A team proudly reports: "Our docs are great—we have one comprehensive 'User Guide' that covers absolutely everything about the product in a single, thorough document, so users never have to look in multiple places." Using this chapter, explain why this is a symptom of a problem, not the achievement they think it is. What are users of that guide actually experiencing?

D4. The diagnostic chain. Three chapters have now given you three versions of essentially one diagnostic test: Chapter 22's "watch a beginner try," Chapter 25's "clean-machine test," and this chapter's "fresh-environment run / watched beginner." Write a short paragraph explaining what single underlying principle these three tests all exploit, and why that principle means the author can never be the tester.

D5. When the framework bends. Diátaxis is a tool for thinking, not a rigid law. Describe one realistic situation where the boundary between two modes is genuinely fuzzy (e.g., a README quick-start vs. a short tutorial), and argue what matters more than picking the "correct" quadrant.

Part M — Mixed Practice (Interleaved) ⭐⭐–⭐⭐⭐

These mix this chapter with earlier ones. Decide which chapter's tool applies before you solve.

M1. A document has numbered steps. That alone doesn't tell you what it is. Given these three numbered-step documents, decide for each whether the governing chapter is 22 (instructions/procedures), 25 (a README quick-start), or 26 (a tutorial)—and justify: (a) a 6-step office procedure for resetting a conference-room projector; (b) the "Quick Start" section of an open-source library's README; (c) a standalone "Your First Project" page on a framework's learning site. (Hint: they can overlap—say what each primarily is and why.)

M2. You're writing a tutorial and you hit a step with a genuine safety/destructive risk ("this command permanently deletes the folder"). Chapter 26 says tutorials walk the happy path and defer caveats; Chapter 22 says a warning goes before the dangerous step. Which wins, and why? Write the step as you'd actually ship it.

M3. A how-to guide includes a code example, and Chapter 24's lesson was "comment the why, not the what." Take this over-commented how-to snippet and fix the comments so they explain why where it helps and say nothing where the code is self-evident:

"for line in f: # loop over each line in the file if not line.strip(): continue # if the line is empty, skip it parse(line, strict=True) # parse the line with strict set to True"

M4. Chapter 4 taught informative headings (name the content, not the form). Three tutorial/how-to headings below are weak. Rewrite each to name what the reader gets, and say whether the rewrite signals a tutorial or a how-to: (a) "Introduction"; (b) "Advanced Usage"; (c) "Examples."

M5. Chapter 7 distinguished register (formal/neutral/informal) and tone. A tutorial and a how-to for the same tool will differ in tone even when the topic is identical. In one sentence each, characterize the tone a tutorial takes versus a how-to, and tie each tone choice to the reader's situation (beginner vs. competent).

M6. Chapter 2's curse of knowledge, Chapter 22's assumed step in instructions, and Chapter 26's assumed step in tutorials are the same phenomenon at three scales. Write one before/after pair of your own (a step with a hidden assumption → the step with the assumption made explicit) drawn from any task you know well, and label what state-of-the-world the original silently assumed.

Part E — Extension ⭐⭐⭐⭐ (optional)

E1. Build a documentation map. For a tool or project you know well (or one you'd like to start), design the full Diátaxis structure: list the tutorials it needs (probably 1–3), the how-to guides (the specific tasks users actually have), the reference pages, and the explanations. Then mark which you'd write first and defend the order in terms of audience need, not completeness. (Most projects should write one tutorial and a handful of how-tos before anything else—argue whether yours is the exception.)

E2. The graduation problem. A tutorial carries a beginner to one success; a how-to assumes competence. Write a short essay (~300 words) on the gap between them: how does a reader get from "I finished the tutorial" to "I can now use the how-tos"? What can documentation do to ease that transition (e.g., a "next steps" ladder, an intermediate tutorial), and where is the line past which it's the reader's job to build competence, not the docs'?

E3. Audit a real tutorial for assumed steps. Take a published tutorial for a tool you do not already know (so your own curse of knowledge can't fill the gaps), and actually follow it on a clean setup. Log every place you stall. Then categorize each stall: assumed step? undefined term? environment assumption? broken example? Report what fraction of the stalls re-reading the tutorial would never have caught—and what that implies about how the author should have tested it.

Self-Assessment Rubric (for the open-ended Write/Revise tasks)

Score each produced document against these. A strong piece earns "yes" on all of them.