Further Reading — Chapter 34: Writing for Computer Science

Annotated, and limited to sources that are real and verifiable (Tier 1) or widely-attributed ideas whose exact citation details vary (Tier 2), per this book's citation-honesty standard. These are the references a working engineer-writer actually reaches for.

On code review

  • Google's Engineering Practices documentation — the Code Review Guide (google.github.io/eng-practices). (Tier 1.) The single best free resource on the writing of code review, and the basis for some of this chapter's vocabulary. It has two halves worth reading together: "How to do a code review" (the reviewer's guide—what to look for, how to write comments, how to navigate disagreement) and "The CL author's guide" (how to write a change and its description so it can be reviewed well, including small PRs and good descriptions). Concrete, opinionated, and battle-tested at enormous scale. Read it for exercise E1.
  • Practitioner writing on the social dynamics of code review. (Tier 2.) A large body of engineering-blog and conference writing argues what §34.1 argues—that the tone and framing of review comments shape team health as much as the technical content, and that "critique the code, not the coder" is a practical necessity, not etiquette. No single canonical text; search "kind code review" or "code review culture" for current talks. (The underlying principle—separate the artifact from the person—is the durable part; the specific conventions vary by team.)

On postmortems and the blameless tradition

  • The Site Reliability Engineering tradition's postmortem practice. (Tier 1 for the practice's existence and core tenets.) The blameless postmortem as a hard organizational norm was formalized and popularized in large part by the site-reliability-engineering movement at companies operating at massive scale; the publicly available Site Reliability Engineering material includes a chapter on postmortem culture and example templates. The central tenets §34.6 builds on—blamelessness, a neutral timeline separated from analysis, system root causes, action items that change the system—are spelled out there. Essential for exercise E2.
  • The literature on "human error" and systems thinking in safety-critical fields. (Tier 2.) The idea that "human error" is a *starting point for investigation, not a conclusion"—and that resilient systems are designed assuming people will err—comes from decades of human-factors and safety research (aviation, medicine, industrial operations) that the software postmortem tradition borrowed from. The phrase "why was it possible?" and the move past the proximate cause to the system cause trace to this lineage. Search "just culture" and "systems thinking safety" for the foundational ideas. (Connects to Chapter 38's ethics cases, where communication failures in safety-critical systems caused real harm.)

On user stories, acceptance criteria, and specs

  • The agile/user-story tradition (the "As a… I want… so that…" template and Given-When-Then). (Tier 2.) The user-story format and the Given-When-Then structure for acceptance criteria are widely-used conventions across the agile software community; they're attributed across many practitioners and books rather than to a single canonical source. What's durable is the function §34.4 stresses—forcing the who/what/why, and making "done" a testable contract—not any particular ceremony. (Pairs with Chapter 33's requirements language: an acceptance criterion is a testable "SHALL" for a feature.)

On the foundations this chapter builds on (within this book)

  • Chapter 24 (Code Documentation) and Chapter 25 (README/API docs). The direct prerequisites: "comment the why, not the what" (Ch 24) is what a PR description and a design doc's why scale up; "API docs are a contract; document the errors" (Ch 25) is the same "document the failure, not just the success" instinct that runs through bug reports, acceptance criteria, and postmortems.
  • Chapter 21 (Workplace Reports). The incident report (summary / timeline / root cause / corrective actions, owners and dates, blameless framing) is the deliberate ancestor of §34.6's postmortem. This chapter elevates the blameless principle from one practice to the organizing one and supplies the mechanism for why it's necessary.

On clarity and conciseness, applied to a code block

  • William Zinsser, On Writing Well; Strunk & White, The Elements of Style. (Tier 1.) The conciseness that makes a good PR title, a one-line bug summary, and a tight review comment land is the same "omit needless words" these books teach—now applied to the writing around code. The marketing-fluff release-notes failure (§34.7) is their "avoid the inflated phrase," in announcement form.

Where to start: If you read only two things, read Google's "How to do a code review" (it will change how you leave comments tomorrow) and the SRE postmortem-culture material (it will change how your team writes about failure). Then carry the one idea both share into every collaborative document you write: aim at the work, not the person.

Back to: Chapter 34 · Key Takeaways