Quiz — Chapter 25: README Files, API Documentation, and Developer-Facing Writing

Target: 70%+ before moving on. Answers and explanations are hidden under each question—try first, then check.

Section 1 — Multiple Choice

1. What is the single most important section of a README?

  • A) The motivation and background, explaining why the project exists
  • B) The architecture overview, so readers understand the design
  • C) The quick-start: the shortest path to a working example
  • D) The contributing guidelines, to attract collaborators
Answer**C.** The quick-start—an install command plus a runnable example—is what gets a stranger from "found this" to "it works," and time-to-first-success is the metric that matters most. A reader who gets a quick win trusts the tool and reads on; one who gets stuck leaves. (A) and (B) are the philosophy and internals that belong *below* the quick-start or in linked docs—leading with them is the "wall of text" failure (Raj's original README, §25.1–25.2). (D) matters but serves a much smaller audience (would-be contributors) than the quick-start (every visitor). See §25.2.

2. Raj's original chronoparse README was 800 words of well-written, accurate prose about how date parsing works. Why did it fail?

  • A) It was too short to cover the project adequately
  • B) It contained factual errors about date parsing
  • C) It answered questions the reader didn't have and omitted an install command and a runnable example
  • D) It used too much technical jargon for a general audience
Answer**C.** The README answered Raj's question (his philosophy of date parsing) instead of the *visitor's* questions (what is this, how do I install it, show me an example), and it never gave an install command or a runnable example—the two things a developer needs most. Quality of prose is irrelevant when it's the wrong content in the wrong order (the audience principle, [Chapter 2](../../part-01-writing-is-thinking/chapter-02-audience/index.md)). (A) is backwards—the rebuilt README was *shorter* and far more useful. (B) is wrong; the prose was accurate. (D) misses it—the audience is developers, who *want* the technical specifics; the problem was missing *actionable* content, not jargon. See §25.1.

3. The chapter's threshold concept is that documentation is the product's user interface for developers. What practical priority shift follows from crossing this threshold?

  • A) Optimize the README for completeness—cover everything you know about the project
  • B) Optimize for time-to-first-success—get a stranger to a working result fast; move the architecture essay out of the doorway
  • C) Write the docs only after the code is finished and stable
  • D) Prioritize beautiful formatting and badges over content
Answer**B.** If the docs *are* the interface a developer touches, then the priority is how fast a stranger gets a working result, not how much you explain—so the quick-start jumps to the top and the philosophy moves down or out. (A) is the pre-threshold instinct (length signals effort) that produces walls of text. (C) treats docs as an afterthought, the exact mindset the threshold overturns. (D) confuses surface polish with the actual job (getting the reader to success). See the Threshold Concept box in §25.1.

4. Why is a runnable code example more useful than an accurate prose description of how a library works?

  • A) Prose descriptions are always inaccurate
  • B) Examples are shorter and take less space
  • C) An example shows the exact syntax and result in the medium the reader will use, is verifiable, and is adaptable—it answers "what will using this be like?" directly
  • D) Readers can't understand technical prose
Answer**C.** A runnable example answers the reader's real question ("what will it be like to use this in *my* code?") in the exact medium they'll use, shows the precise syntax and the actual return value, can be *verified* by running it, and can be *adapted* by copy-paste—none of which prose does. (A) and (D) are overstated; good prose can be accurate and understandable, it just answers a *different* question (how it works internally) the reader then has to translate. (B) is a side benefit, not the reason. See §25.2, "Why Does This Work?"

5. In API documentation, which part do developers need most and writers most often omit?

  • A) The endpoint's URL
  • B) The error responses (status codes, stable error codes, and meanings)
  • C) The project's license
  • D) The author's contact information
Answer**B.** Integration code spends most of its logic handling *failure*, and the failure behavior is exactly what a developer can't guess from outside—yet it's the most commonly omitted part of API docs. Without it, the integrator must trigger every error in testing to learn the shapes, and will miss some (which surface in production). (A) is usually present. (C) and (D) aren't part of endpoint reference docs. See §25.4 and its "Check Your Understanding."

6. What are the core sections of an Architecture Decision Record (ADR)?

  • A) Title, Author, Date, Summary
  • B) Problem, Solution, Code, Tests
  • C) Context, Decision, Consequences (often with Status)
  • D) Introduction, Methods, Results, Discussion
Answer**C.** An ADR captures **Context** (what forced the decision), the **Decision** itself, and the **Consequences** (the trade-offs accepted, including downsides), usually with a **Status**. The format was popularized by Michael Nygard. (D) is IMRaD—the structure of a lab report ([Chapter 13](../../part-03-academic-scientific-writing/chapter-13-lab-reports/index.md)), not an ADR. (A) and (B) miss the defining content: the *why* (context) and the *trade-offs* (consequences). See §25.5.

7. Why does an ADR record the rejected alternatives and the costs of a decision, not just what was chosen?

  • A) To make the document longer and more impressive
  • B) So a future maintainer who reconsiders the decision knows what it was weighed against and what it cost—preventing them from re-litigating it or undoing it blindly
  • C) Because the rejected options might still be implemented later
  • D) To assign blame if the decision turns out wrong
Answer**B.** An ADR's value is realized in the future, when someone reconsiders the decision; to do that intelligently they need the alternatives weighed (so they don't repeat a failed experiment) and the costs accepted (so they know the condition under which to revisit). A decision recorded without its context and consequences is just an assertion a successor can't evaluate. (A) is the opposite of the chapter's "short is the point." (C) misreads it—rejected options are recorded as *history*, not a backlog. (D) is contrary to the blameless spirit of good engineering docs. See §25.5, "Why Does This Work?"

8. What distinguishes a changelog from a git commit log?

  • A) Nothing—a changelog is just a formatted commit log
  • B) A changelog is curated for the user deciding whether to upgrade; a commit log records what each developer did
  • C) A commit log is for users; a changelog is for developers
  • D) A changelog must be written in a programming language
Answer**B.** The audience distinction is the whole skill: a commit log answers "what did each developer do?" (internal, noisy, full of "wip" and "fix tests"); a changelog answers "what do I, a user, need to know to upgrade safely?" (curated, grouped by Added/Changed/Fixed/Breaking, leading with breaking changes). (A) and (C) invert or collapse the distinction. (D) is nonsense. See §25.6.

9. A library is releasing a version that removes a function parse_strict(). What is the single most valuable thing to include in the changelog entry?

  • A) The name of the developer who removed it
  • B) The commit hash where it was removed
  • C) A migration path: what to use instead (e.g., "pass strict=True to parse()")
  • D) An apology for the inconvenience
Answer**C.** A migration path turns "this broke my code" into "here's the one-line fix"—it's the most valuable line in any changelog. "X was removed" abandons the reader; "X was removed; use Y instead" rescues them. Every breaking change should include one. (A) and (B) are commit-log internals users don't need. (D) is noise. See §25.6.

10. What is the purpose of a CONTRIBUTING.md file?

  • A) To list everyone who has ever contributed
  • B) To equip a willing-but-uncertain contributor with the setup, test, style, and process knowledge they need to submit a successful change
  • C) To replace the README
  • D) To document the legal terms of contribution only
Answer**B.** A contributing guide removes the uncertainties—how to set up locally, run tests, follow the style, propose a change—where a willing contributor would otherwise quietly give up. It's instructions ([Chapter 22](../../part-04-professional-workplace-writing/chapter-22-instructions-procedures/index.md)) for a specific doer: a developer who wants to help but needs your process. "PRs welcome" is an open door with no map. (A) describes a contributors *list*, a different thing. (C) is wrong—it complements, not replaces, the README. (D) is too narrow; legal terms are one small part. See §25.7.

11. The "open-source documentation standard" refers to:

  • A) A formal specification ratified by a standards body that projects must follow
  • B) The set of documents (README, API/reference docs, ADRs, changelog, contributing guide) that experienced developers expect a healthy, usable project to have
  • C) A single required file format for all documentation
  • D) A legal requirement for open-source licensing
Answer**B.** It's an *expectation* experienced developers carry, not an enforced rule: a project that meets it signals "maintained, usable, welcoming," and one that doesn't signals "use at your own risk." Tooling increasingly expects these files too. (A) overstates it—there's no ratifying body. (C) and (D) are wrong; it's about which *documents exist*, not a format or a license term. See §25.7.

12. Why is the "clean machine" test the software equivalent of Chapter 22's "watch a beginner try"?

  • A) Because clean machines are faster than used ones
  • B) Because a clean machine lacks all the assumed context (installed dependencies, env vars, config) that your machine has, so it stalls exactly where your README assumes something it never stated
  • C) Because beginners only ever use new computers
  • D) Because it tests the code, not the documentation
Answer**B.** A clean machine has none of the contamination your own machine accumulated—the dependencies, environment variables, and config you set up months ago and forgot—so it fails precisely where your README assumes the reader has them, just as a human beginner fails where your instructions assume knowledge they lack. Your own machine, like your own mind, is contaminated with context that hides the gaps (the curse of knowledge, [Chapter 22](../../part-04-professional-workplace-writing/chapter-22-instructions-procedures/index.md)). (A) and (C) miss the point entirely. (D) is wrong—it tests whether the *documentation* gets a newcomer set up. See §25.2 and the Spaced Review.

Section 2 — True/False with Justification

State true or false and justify in one sentence. The justification is where the learning is.

T1. A longer, more comprehensive README is generally a better README.

Answer**False.** A README is measured by time-to-first-success, not length; Raj's rebuilt README was *shorter* than his original and vastly more useful because it answered the reader's questions in order instead of burying the install command under a philosophy essay. Comprehensiveness belongs in linked reference docs, not the doorway. (§25.1–25.3)

T2. A curl or code example in documentation can be slightly out of date without much harm, since readers will understand the intent.

Answer**False.** An example that errors on the first line destroys trust instantly and teaches the reader a falsehood (a stale field, a renamed function, a missing header), and it generates bug reports; examples must actually run, which is why you test them on a clean setup or in CI. (§25.2, §25.4)

T3. Once you write an ADR, you should edit it whenever the decision changes, to keep it current.

Answer**False.** ADRs are append-only history: you don't edit an old ADR when your thinking changes, you write a *new* one that supersedes it (and mark the old one's status "Superseded"), because the value is the *log* of how the team's reasoning evolved, not a single always-current statement. (§25.5)

T4. API documentation only needs to describe successful requests; developers can figure out errors on their own.

Answer**False.** Failure handling is where integration code spends most of its effort, and error behavior is invisible from outside the system, so omitting it is the most painful possible gap—forcing developers to trigger every failure in testing (and miss some); document status codes, stable error codes, and meanings. (§25.4)

T5. A README's feature list reading "powerful, flexible, fast, and intuitive" effectively communicates the project's capabilities.

Answer**False.** Those are unverifiable adjectives every project claims, so they carry no information (the empty-intensifier problem, [Chapter 7](../../part-02-building-blocks/chapter-07-word-choice-tone-voice/index.md)); concrete capabilities a reader can map to their need ("resolves against any reference time," "zero dependencies") communicate, adjectives don't. (§25.3)

T6. Documentation that was correct once but is now subtly wrong is roughly as harmful as having no documentation at all.

Answer**False—it's worse.** No docs makes the reader cautious and forces them to verify; *wrong* docs the reader *trusts*, so they build on a falsehood and fail in ways that are hard to diagnose, which is why keeping docs near the code, generating reference from source, and treating "update the docs" as part of "done" matter. (§25.8)

Section 3 — Short Answer

A model answer and a one-line rubric follow each.

S1. In one or two sentences, explain why the README is called the "front door" of a project, and what the consequence is when that door is "locked."

Model answer + rubric**Model:** The README is the first—and often only—thing a developer reads before deciding whether to use a project, so it's where a stranger forms a thirty-second judgment about whether the project is alive and worth their time; when it's "locked" (no install command, no example, a wall of philosophy), the visitor can't get in, leaves, and often builds their own tool instead—exactly Raj's eleven lost users. **Rubric:** Credit for (1) README = first/only thing read, the decision point; (2) the consequence: the unable-to-start visitor leaves. (§25.1)

S2. List the five things that make a single API endpoint's documentation complete (such that a developer can use it without reading the source).

Model answer + rubric**Model:** (1) What it does (purpose); (2) the request (every field, type, required-or-not, constraints); (3) the response (the actual body and the status code); (4) the errors (status codes, stable error codes, and meanings); (5) a runnable example (a `curl` command or snippet). **Rubric:** All five for full credit; "errors" is the one most likely to be missed and the one the chapter stresses most. (§25.4)

S3. Explain the difference between the what (which code shows) and the why (which only an ADR preserves), using a concrete example.

Model answer + rubric**Model:** The *what* is visible in the artifact—e.g., you can read the code and see the system uses parser combinators for its grammar engine. The *why* is not recoverable from the code—that the team tried regexes first, abandoned them for three specific reasons (ambiguity, opaque errors, no extensibility), and accepted a 15% performance cost to switch; the ADR preserves that reasoning so a future maintainer doesn't mistake a hard-won choice for an arbitrary one and undo it. **Rubric:** Credit for a clear *what*/*why* split tied to a concrete decision, and for naming that the *why* is unrecoverable from code. (§25.5; [Chapter 24](../chapter-24-code-documentation/index.md))

S4. Why should a changelog be grouped by change type (Added/Changed/Fixed/Breaking) and lead with breaking changes?

Model answer + rubric**Model:** Because a changelog serves a user deciding whether and how to upgrade, and grouping by change type lets a cautious upgrader jump straight to the sections that can ruin their day—Breaking and Deprecated—and decide in seconds whether the upgrade needs care; leading with breaking changes makes the most time-costly information impossible to miss. **Rubric:** Credit for (1) audience = upgrading user, (2) breaking/deprecated = the high-cost-if-missed entries that earn the lead. (§25.6)

S5. Name two concrete defenses against documentation drifting out of sync with the code, and say which is strongest.

Model answer + rubric**Model:** Defenses include: (1) keep docs in the same repo and the same pull request as the code so they're updated together; (2) test examples automatically (run README/`curl` examples in CI) so a broken example fails the build; (3) generate reference docs from the source (docstrings, OpenAPI) so they *can't* drift; (4) treat "update the docs" as part of the definition of "done." The strongest is generating reference from the source, because it removes the possibility of drift entirely rather than relying on discipline—the docs and the code are the same artifact. **Rubric:** Credit for any two concrete defenses plus a defensible "strongest" with reasoning (generation is the model answer because it's structural, not discipline-dependent). (§25.8)

Section 4 — Applied Scenario

A small writing task, graded by rubric.

A1. You've inherited a small internal tool, logtidy, that cleans up and deduplicates messy application log files. It has no README. You know: it's a Python CLI, installed with pip install logtidy (internal registry), Python 3.10+; the basic command is logtidy clean access.log > cleaned.log; it has a --dedup flag to remove duplicate lines and a --since DATE flag to keep only lines after a date. Write the top section of a README for it: a one-line description, a short feature list, an installation block, and a quick-start with a runnable example showing a command and a sample of its output.

RubricScore 0–2 each: - **One-liner:** Does it say, concretely, what `logtidy` does in one sentence? (Concrete beats "a powerful log utility.") - **Install:** Is the exact command in a code block, with the Python version requirement on one short line? - **Quick-start:** Is there a runnable example—an actual command—showing both the invocation *and* what the reader gets back (a sample of output)? - **Features:** Are the flags (`--dedup`, `--since`) presented as concrete capabilities, not adjectives? - **Order:** Does it lead with what-it-is and the quick-start, with no philosophy wall on top? A strong answer (8/10+) is something a teammate could use in two minutes. Anything missing the install command or the runnable example is the core failure this chapter warns against—dock heavily.

A2. Document one endpoint, completely, to the §25.4 standard: DELETE /links/{id} for a URL-shortener API (it deletes a short link). Include a one-line purpose, the path/auth, the success response (status code + body, if any), and an errors table with at least three realistic failures (status + stable error code + meaning), plus a runnable curl example.

RubricScore 0–2 each: - **Purpose + auth:** Stated clearly? - **Success response:** Correct status code for a delete (e.g., `204 No Content` or `200` with a body), and is the body (or its absence) shown? - **Errors table:** At least three realistic failures with status code, a *stable* error code (e.g., `link_not_found`, `unauthorized`, `forbidden`), and a plain-language meaning? - **Runnable example:** A `curl` command with the auth header that a developer could actually run? - **Source-independence:** Could a developer use this endpoint without reading your code? Full marks (8/10+) require the errors table—omitting it is the exact gap the chapter calls the most painful, so it's the heaviest-weighted dimension.

Scoring & Next Steps

Score What it means Do next
< 50% Core ideas haven't landed yet Re-read §25.1–25.3 (the README and quick-start) and §25.4 (API docs); redo Section 1.
50–70% Partial grasp Redo Part B of the exercises (the "revise this" tasks)—they target the gaps most quizzes expose.
70–85% Solid Proceed to Chapter 26. Do the Project Checkpoint: write or fix one real README and run the clean-machine test.
> 85% Strong Try the Deep Dive: exercises E1 (OpenAPI) and E2 (audit a real project's docs against the open-source standard).

The one test that matters more than this quiz: could a stranger get your project working from your README alone? Go run the clean-machine test on something you've written, and let the stalls grade you.