Writing Documentation: Phrases for READMEs, ADRs and Runbooks
5 exercises on key technical writing phrases. Choose the most natural and professional option.
0 / 10 completed
1 / 10
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 / 10
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 / 10
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 / 10
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 / 10
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.
6 / 10
Alice, a senior developer, is reviewing your pull request for a new user authentication endpoint. She comments: 'This implementation doesn't clearly state the expected input format or error handling strategies.' Which of the following phrases would be MOST effective in responding to her feedback while documenting this API endpoint?
Alice's comment highlights a lack of clarity in the documentation. The correct answer emphasizes that the documentation should *specifically* address the input format and error handling – precisely what she requested. Options A and D are too vague or dismissive; option B is unprofessional and suggests delaying necessary documentation. Option C directly addresses her concern.
7 / 10
You're drafting a Slack message to announce a temporary outage affecting the production database. Which of the following messages is MOST professional and informative for your development team?
The correct response clearly communicates the issue (production DB outage), acknowledges its impact (downtime), and promises further communication. Option A is overly terse and lacks context; option B is less detailed but better than A. Options C and D are too informal or alarmist for a professional announcement.
8 / 10
You've received the following API response from a third-party service: `{"status": "error", "code": 400, "message": "Invalid request parameters."}`. Which phrase is BEST for documenting this potential error scenario in your application's documentation?
The API response clearly shows an error. The correct phrasing explains that the 'status' being 'error' indicates a problem with the data provided to the service – this is the key piece of information to convey. Options A and D are incorrect; option B is too technical for general documentation, while B is dismissive.
9 / 10
You're writing a Runbook for restarting a specific microservice. Before detailing the commands, what's the MOST effective phrase to include at the beginning to guide the operator?
The most crucial aspect of a runbook is providing clear instructions for safe operation. Option A is simply stating the obvious; option B emphasizes caution. The correct answer stresses pre-restart checks (monitoring resource utilization and application logs) – this is vital to prevent cascading failures or unintended consequences. Option D is completely inappropriate for documentation.
10 / 10
You are writing an ADR (Architecture Decision Record) detailing the decision to migrate your application's database from MySQL to PostgreSQL. Which phrase BEST captures the primary justification for this architectural change?
The correct answer focuses on the *reasoning* behind the decision – improved concurrency and data integrity are key architectural drivers. Option A is simply stating an arbitrary choice; option B provides a more detailed explanation but doesn't directly address the core justification. Option C is too simplistic, while option D lacks any rationale.
What will I practise in "Writing Documentation: Phrases for READMEs, ADRs and Runbooks"?
This module focuses on Phrasebook — real workplace phrasing you'll use on the job. It contains 10 scenario-based multiple-choice questions with instant feedback.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to use with no account or sign-up required.
How many questions does this exercise have?
This module includes 10 questions. Each one gives an immediate right/wrong result plus a full explanation of the correct phrasing.
What happens if I answer a question incorrectly?
You'll see the correct answer highlighted straight away, along with a plain-English explanation of why it's right and why the other options don't fit — mistakes are part of the learning here.
Can I retry the exercise if I want a better score?
Yes — use the 'Try again' button on the results screen to reset your score and go through the questions again. There's no limit on attempts.
Who is this Phrasebook exercise for?
It's aimed at IT professionals with working English who want to sound more natural and precise around phrasebook — useful whether you're preparing for real conversations at work or just building confidence with the vocabulary.
Do I need an account to track my progress?
No account is needed. Your progress through the exercise is tracked locally in your browser for the current session, and you can replay the module at any time.
How is this different from reading a blog article?
This exercise is an interactive drill that tests and reinforces specific phrasing through multiple-choice questions with instant feedback, while blog articles explain concepts and vocabulary in prose. The two work well together.
Where can I find more Phrasebook exercises?
See the Phrasebook hub for more modules like this one, or browse the full Exercises page for other IT-English topics.
Can I complete this exercise on my phone?
Yes — every exercise on CoderSlingo is fully responsive and works on phones and tablets, so you can practise anywhere.