A runbook is a documented procedure that tells an on-call engineer exactly what to do when a specific incident or operational scenario occurs. A good runbook saves time, reduces errors, and lowers the stress of responding to incidents at 3am. A poor runbook — one that is vague, outdated, or hard to follow — can make incidents worse.
For non-native English speakers writing runbooks, the challenge is producing clear, unambiguous instructions that a stressed engineer can follow at speed. This guide covers the structure, language, and style you need.
The Purpose of a Runbook
A runbook is not a design document or a tutorial. It is a procedural reference — like a pilot’s checklist. It should be:
- Specific — written for one scenario, not a general guide
- Actionable — every step tells the reader what to do, not what to know
- Current — runbooks that are out of date are dangerous
- Scannable — use numbered steps, not paragraphs
Standard Runbook Structure
1. Title and Metadata
Title: Payment Service High Latency Response Procedure Service: payments-api | Owner: Payments Team | Last updated: 2026-06-14 Alert:
PaymentsAPILatencyHigh— P99 latency > 2 seconds for 5 minutes
2. Overview
One or two sentences describing the scenario and the typical cause.
“This runbook covers the response procedure for elevated latency in the payments API. Common causes include database connection pool exhaustion, downstream timeout storms, and traffic spikes exceeding autoscaling capacity.”
3. Severity and Escalation Path
“Severity: P1 (revenue impact). Escalate to the Payments team lead if not resolved within 30 minutes. Notify the Head of Engineering if customer-facing impact exceeds 15 minutes.”
4. Prerequisites
“Before following this runbook, ensure you have: - Access to the production AWS console - Access to the Datadog dashboard (link below) - The payments-api channel open in Slack”
5. Diagnostic Steps
This section tells the on-call engineer how to understand what is happening.
6. Resolution Steps
This section tells the on-call engineer how to fix it.
7. Post-Incident Actions
What to do after the incident is resolved.
Writing Diagnostic Steps
Use clear, numbered imperative sentences. Each step should have one action.
Good Diagnostic Language
“1. Open the Payments API Datadog dashboard: [link]”
“2. Check the P99 latency graph for the past 30 minutes. Note whether the spike is gradual or sudden — gradual spikes indicate resource exhaustion; sudden spikes indicate a traffic event or deployment.”
“3. Check the database connection pool metrics: navigate to RDS → payments-db → Performance Insights.”
“4. Check for recent deployments: run
gh run list --workflow=deploy --repo=payments-api --limit=5.”
“5. Check for upstream traffic anomalies in the API gateway logs. Filter by
service=paymentsfor the affected time window.”
Decision Trees
Use explicit conditional logic when the next step depends on what the engineer finds:
“If the connection pool is saturated (active connections > 90%):” ” → Proceed to Section A: Database Connection Pool Exhaustion“
“If a recent deployment correlates with the latency spike:” ” → Proceed to Section B: Rollback Procedure“
“If no deployment or connection issue is found:” ” → Proceed to Section C: Traffic Spike Investigation“
Writing Resolution Steps
Resolution steps must be even more precise than diagnostic steps. The engineer is now taking action that could affect production.
Use the Imperative Mood
Write every action as a direct command. Do not use passive voice or hedge:
Weak (passive/hedged):
“The deployment should probably be rolled back if the issue is confirmed to be related to the latest release.”
Strong (imperative):
“If the issue is confirmed to be deployment-related, roll back immediately using the following command:”
Include Exact Commands
“Run the following command to restart the payment worker pods:” “
kubectl rollout restart deployment/payments-worker -n production”
“To roll back to the previous deployment:” “
kubectl rollout undo deployment/payments-api -n production”
“Verify the rollout is complete:” “
kubectl rollout status deployment/payments-api -n production”
Include Expected Outcomes
Tell the engineer what success looks like:
“The P99 latency should begin dropping within two to three minutes of the restart. If latency does not improve within five minutes, proceed to escalation.”
Post-Incident Actions
“1. Post an incident summary in the
#incidentsSlack channel using the template pinned to the channel.”
“2. Update the incident ticket in PagerDuty with root cause and resolution.”
“3. If the runbook needs updating based on this incident, open a PR with the changes and assign it to the team lead for review.”
“4. Schedule a postmortem if the incident lasted more than 30 minutes or had customer impact.”
Common Runbook Writing Mistakes
Using passive voice for instructions. “The service should be restarted” is ambiguous. “Restart the service” is not.
Missing the expected outcome. Engineers under stress need to know whether what they just did worked. Always state what success looks like.
Outdated links and commands. A runbook with a dead link to the dashboard or a deprecated CLI command is worse than no runbook. Review runbooks after every relevant system change.
Too much background. Runbooks are not tutorials. Keep explanation to the minimum needed to make a decision. If more context is needed, link to a separate document.
A well-written runbook is one of the most valuable documents a team can have. The best time to write one is during a quiet period, immediately after reviewing a recent incident. The language should be clear enough that a tired engineer, unfamiliar with the system, can follow it successfully at midnight. That is the standard to write to.
Navigating Nuances: English for SRE Runbooks – A Special Focus
Writing effective SRE runbooks isn’t just about listing commands; it’s about communicating clearly and precisely so that anyone – regardless of their background – can quickly understand and execute a solution. For non-native English speakers, this can be particularly challenging due to the density of technical terminology and the often-formal phrasing used in operational documentation. Let’s address some specific areas where careful word choice can significantly improve comprehension and reduce potential misunderstandings.
One common issue arises during code reviews. Imagine receiving a comment on a pull request: “This section lacks sufficient detail regarding rollback procedures.” A native speaker might immediately understand the implied urgency – that the rollback plan needs to be robust and well-defined. However, for someone still developing their professional English, this could feel ambiguous. Better phrasing would be, “To ensure a successful rollback, could you add explicit steps outlining the data migration process following the reversion, including verification checks to confirm data integrity?” This provides concrete instructions and removes any potential ambiguity about what’s expected. Similarly, in Slack discussions, a terse message like “Fix degraded service” isn’t helpful. Instead, consider: “Investigate the root cause of the degraded service impacting users in region X. Please document your findings, including metrics showing the severity and duration of the issue, and propose a remediation strategy.” The added detail – specifying the region, referencing metrics – immediately elevates the communication.
Another key area is structuring PR descriptions. Instead of simply stating “Updated monitoring alerts,” aim for something like: “Implemented new alerting thresholds within Grafana to proactively notify the on-call team of increased CPU utilization exceeding 90% during peak hours. This change aims to reduce Mean Time To Detect (MTTD) and improve overall system stability. The configuration details are documented in [link to config doc].” The inclusion of the goal (“reduce MTTD”), the specific metric being monitored, and a link to supporting documentation demonstrates a thorough understanding and provides context for reviewers. Paying attention to passive voice versus active voice also matters; active voice – “We implemented…” – is generally clearer than passive voice – “Alerts were implemented…” – particularly when describing actions taken by your team.
Finally, be mindful of jargon. While technical terms are necessary, consistently explain their meaning within the runbook’s context. Instead of repeatedly using “latency,” consider defining it as “the time it takes for a request to travel from the user’s device to our servers and back.” This helps ensure everyone understands the terminology equally. Aim for clarity above all else – a slightly longer, more descriptive explanation is always preferable to an ambiguous or potentially misinterpreted instruction.
Keep practising
Turn this article into muscle memory
Five-minute exercises with instant feedback — built from the same kind of real IT language.
What to read next
Frequently asked questions
What will I learn from "How to Write an SRE Runbook in English"?
This is a Intermediate-level Writing article covering writing, sre, runbooks and documentation. Runbook structure, clear imperative instructions, decision trees, and troubleshooting language — a practical guide to writing SRE runbooks in English.
Is this article free to read?
Yes. Every article on CoderSlingo, including this one, is free to read with no account, sign-up, or paywall.
How is reading this article different from doing an exercise?
Articles like this one explain concepts and vocabulary in context through prose, while exercises are interactive drills — fill-in-the-blank, matching, and multiple-choice — that test and reinforce specific terms. Reading builds understanding; exercises build recall.
Can I practice the vocabulary used in this article?
Yes — this article's topic lines up with our writing exercises. Use the "Practice this vocabulary" link below to jump straight into a matching drill.
How long does "How to Write an SRE Runbook in English" take to read?
About 7 min. Most CoderSlingo articles, including this one, are written to be read in one sitting, without needing a dictionary open in another tab.
Do I need to create an account to read or save this article?
No account is required to read any article. If you complete exercises elsewhere on the site, your progress is saved locally in your browser — no login needed.
What if I don't understand a technical term used in this article?
Check the site Glossary for plain-English definitions of common IT terms, or browse the #writing tag page for other Writing articles that use the same vocabulary in different contexts.
Can I share or link to "How to Write an SRE Runbook in English"?
Yes — use the Twitter/X or LinkedIn share buttons at the end of the article, or copy the page URL directly. Attribution back to CoderSlingo is appreciated but the content is free to reference.
When was this Writing article published?
This article was published in 2026. New Writing articles are added regularly — visit the #writing tag page to see the full, continuously updated list.
Where can I find more articles like this one?
See "How to Write Technical Runbooks in English", "How to Write a Post-Mortem Report in English", "How to Write a Release Notes Summary in English" in the Related Articles section below, or browse all Writing articles from the main Blog index.