Writing Documentation: Phrases for READMEs, ADRs and Runbooks
5 exercises on key technical writing phrases. Choose the most natural and professional option.
0 / 5 completed
1 / 5
How should you open a README or technical document to orient the reader?
DOCUMENT SCOPE OPENING: "This document describes..." is the standard technical writing opener for READMEs, ADRs, and runbooks. It immediately tells the reader what they will learn and why this document exists. Examples: "This document describes the on-call runbook for the orders service, including escalation paths and common failure modes." / "This document describes the Architecture Decision Record for migrating from REST to gRPC, including context, alternatives, and consequences." / "This document describes how to set up the local development environment, from zero to running tests." Options B/C are too casual or circular. Option D is a directive that adds no information and slightly patronises the reader.
2 / 5
You need to list what a reader needs before following a runbook. Which format is most scannable and professional?
PREREQUISITES SECTION: "Prerequisites:" followed by a bulleted or inline list is the canonical technical writing pattern. It lets readers self-qualify before wasting time on steps they cannot complete. Examples: "Prerequisites: Python 3.11+, a local Postgres instance running, and the .env file populated from the team vault." / "Prerequisites: read access to the GitHub repo, npm 9+, and Node 20 LTS." / "Prerequisites: familiarity with Docker Compose and a working VPN connection to the staging environment." Options A/B are vague and force readers to guess. Option C externalises the information rather than providing it.
3 / 5
You are writing an ADR (Architecture Decision Record) and need to explain why the decision was made. Which phrase opens the rationale correctly?
ADR DECISION RATIONALE: "This decision was made because..." anchors the ADR in objective reasoning — constraints, requirements, and trade-offs. Future readers need to understand the forces at play, not just the conclusion. Examples: "This decision was made because the team needed independent deploy cycles, and the monolith's shared database was causing cascading failures." / "This decision was made because GDPR compliance requires data residency in the EU, and our existing CDN doesn't support EU-only routing." / "This decision was made because the client SDK had a breaking change in v3 and maintaining two SDK versions was not sustainable." Options A/C/D lack the specific reasoning that makes an ADR useful to future engineers.
4 / 5
You need to document the limitations of a system or document. Which phrasing is most professional?
KNOWN LIMITATIONS SECTION: "Known limitations:" is the standard technical writing pattern for documenting what a system, runbook, or tool does not handle. It prevents misuse and sets accurate expectations. Examples: "Known limitations: this script does not handle tables with more than 1M rows — use the chunked migration script for large datasets." / "Known limitations: the API does not support pagination; all results are returned in a single response." / "Known limitations: this guide covers Linux and macOS only. Windows setup differs and is tracked in issue #142." Options A/B/D are vague, informal, or off-putting — none of them give readers the specific boundary conditions they need.
5 / 5
You want to invite contributions to a codebase in the README. Which phrase is most welcoming and useful?
CONTRIBUTION GUIDANCE: "To contribute, see..." with a named file and a brief preview of what it contains is the professional standard. It lowers the barrier for contributors by showing them exactly where to start. Examples: "To contribute, see CONTRIBUTING.md — it covers local setup, the PR template, and our code style guide." / "To contribute, open an issue first to discuss the change, then see CONTRIBUTING.md for the PR workflow." / "To contribute: fork the repo, create a branch from main, and submit a PR targeting the develop branch. See CONTRIBUTING.md for the full guide." Options B/C/D are either too terse, too casual, or too vague to actually help someone get started.