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

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 developer-writer actually reaches for.

On the why behind decisions (ADRs)

  • Michael Nygard, "Documenting Architecture Decisions" (2011). (Tier 1.) The short, foundational blog post that popularized the lightweight Architecture Decision Record and its Context / Decision / Consequences format. The whole idea of §25.5 traces to here. It's brief—read the original; it makes the case better in a page than any summary can.
  • Michael Nygard, Release It! Design and Deploy Production-Ready Software. (Tier 1.) Broader than documentation, but the mindset behind ADRs—designing and operating systems that survive contact with reality, and recording why—runs throughout. Useful for understanding the kinds of decisions worth an ADR.

On the kinds of documentation (and why mixing them fails)

  • Daniele Procida, the Diátaxis framework (diataxis.fr). (Tier 1.) The framework this chapter leaned on and Chapter 26 develops fully: four distinct documentation types—tutorials (learning-oriented), how-to guides (task-oriented), reference (information-oriented), and explanation (understanding-oriented)—and why blending them produces muddled docs. The single most clarifying lens for organizing a documentation set. Essential before Chapter 26.

On the open-source documentation standard

  • Keep a Changelog (keepachangelog.com). (Tier 1.) The community convention behind §25.6: a human-readable changelog grouped by Added / Changed / Fixed / Deprecated / Removed / Security, written for users, not as a commit dump. Short, opinionated, and directly usable.
  • Semantic Versioning (semver.org). (Tier 1.) The MAJOR.MINOR.PATCH specification that lets a version number communicate the risk of an upgrade. Pairs with Keep a Changelog: the version number promises, the changelog explains. A few minutes of reading that prevents a career of versioning confusion.
  • The Write the Docs community (writethedocs.org). (Tier 1.) The home community for documentation practitioners—conference talks, a guide, and an active discussion of exactly the genres in this chapter (READMEs, API docs, contributing guides, developer experience). The best place to go deeper and to see how working technical writers think.

On API documentation specifically

  • The OpenAPI Specification (openapis.org). (Tier 1.) The standard machine-readable format for describing REST APIs, and the basis for generating reference docs (and interactive "try it" consoles) that can't drift from the code—the structural fix for the drift problem in §25.8. Referenced in exercise E1. You don't need to master the spec to benefit from understanding what generated, source-of-truth API docs buy you.
  • Research and practitioner writing on "docs-as-code" and developer experience. (Tier 2.) A widely-shared movement holds that documentation should live in the repo, be version-controlled with the code, be reviewed in pull requests, and be tested in CI—treating docs with the same rigor as code. This is the practical answer to doc drift; search "docs as code" for current talks and guides. (No single canonical text; the idea is attributed across the Write the Docs community and many engineering blogs.)

On the foundations this chapter builds on

  • Strunk & White, The Elements of Style; William Zinsser, On Writing Well. (Tier 1.) The conciseness and clarity that make a quick-start example and a one-line description land are the same principles these books teach—now applied to a code block instead of an essay. The feature-list-of-adjectives failure (§25.3) is their "omit needless words" and "avoid the inflated phrase," in marketing form.

Where to start: If you read only two things, read Nygard's ADR post (a page that changes how you record decisions) and the Diátaxis site (the lens that makes every other documentation choice clearer). Then bookmark Write the Docs as your ongoing community.

Back to: Chapter 25 · Key Takeaways