Writing Runbook Documentation in English: Clear, Action-Ready Steps

A runbook is a step-by-step guide for handling an operational task or incident — restarting a service, failing over a database, clearing a stuck queue. It’s read by a stressed engineer at 3 a.m. who needs to act, not interpret. That means runbook English must be ruthlessly clear: short imperative steps, precise verbs, and explicit decision points. This guide shows you how.

---

The golden rule: write commands, not descriptions

Runbook steps are instructions, so use the imperative mood (the command form of the verb). Start each step with a strong action verb.

Descriptive (weak)	Imperative (strong)
“The service should be restarted."	"Restart the service."
"You will need to check the logs."	"Check the logs for OOMKilled."
"It is recommended to scale up."	"Scale the deployment to 5 replicas.”

✅ “Drain the node. Cordon it. Wait for pods to reschedule. Verify traffic has moved before proceeding.”

Every step starts with a verb the reader can do. No “should,” no “it is recommended,” no passive voice.

---

Use precise, unambiguous verbs

Operational verbs have specific meanings. Choosing the right one prevents mistakes.

Verb	Means	Don’t confuse with
Restart	Stop then start	Reload (re-read config without stopping)
Drain	Move work off gracefully	Kill (terminate abruptly)
Failover	Switch to standby	Failback (switch back)
Roll back	Revert to previous version	Roll out (deploy forward)
Throttle	Slow down	Stop
Purge	Delete permanently	Clear (may be reversible)

“Drain the queue (don’t purge it — we need those messages). Then failover to the replica.”

The parenthetical warning prevents a destructive mistake. Always flag verbs that destroy data.

---

Make every step verifiable

After an action, tell the reader how to confirm it worked. A step without verification leaves them guessing.

1. Restart the api pods:

   kubectl rollout restart deployment/api

2. Verify all pods are Running:

   kubectl get pods -l app=api

   ✅ Expected: all pods Running, none CrashLoopBackOff.

The phrase “Expected:” followed by the success condition is a runbook superpower. The reader knows exactly what “done” looks like.

---

Handle decision points explicitly

Real operations branch: “if X, do this; if not, do that.” Write branches as clear conditionals, not buried prose.

3. Check the replica lag:

SELECT now() - pg_last_xact_replay_timestamp();

• If lag is under 5 seconds → proceed to step 4.
• If lag is over 5 seconds → stop. Page the DBA. Do not fail over.

Formatting branches as bullet points with bold conditions makes them scannable under pressure. Use “If… then…” structure and put the dangerous branch’s warning in bold.

---

Write warnings that actually stop people

Generic warnings get ignored. Specific, consequence-stating warnings work.

Weak warning	Strong warning
”Be careful here."	"⚠️ This command drops the table. It is irreversible. Confirm you have a snapshot first."
"This is important."	"⚠️ Do not run this on the primary — only on a replica.”

“⚠️ STOP. The next step deletes production data. Confirm the timestamp matches the incident window before running it.”

State what happens and why it matters. Use ⚠️ and bold sparingly so they retain force.

---

Before and after: a full rewrite

Before (a paragraph nobody can follow at 3 a.m.):

“When the queue is stuck, you should probably look at the consumer and maybe restart it if it seems unhealthy, and you might need to check if messages are being processed, and be careful not to lose data because that would be bad.”

After (scannable, imperative, verifiable):

Runbook: Stuck message queue

1. Check consumer health:

kubectl get pods -l app=consumer

• If pods are CrashLoopBackOff → continue to step 2.
• If pods are Running → the issue is downstream; go to “Downstream checks”.

2. Inspect the logs for the failure reason:

kubectl logs -l app=consumer --tail=100

3. Restart the consumer:

kubectl rollout restart deployment/consumer

✅ Expected: pods return to Running within 60 seconds.

⚠️ Do not purge the queue. Messages must be preserved for replay.

4. Verify messages are draining:

rabbitmqctl list_queues name messages

✅ Expected: the messages count is decreasing.

---

Style rules for runbooks

1. One action per step. Don’t combine “restart and verify and scale” into one line.
2. Number sequential steps; bullet alternatives. Order matters in steps; it doesn’t among branches.
3. Put commands in code blocks, never inline in a sentence where spacing is ambiguous.
4. Write the success condition (“Expected:”) after risky steps.
5. Avoid pronouns. “Restart it” — restart what? Name the object every time.
6. Avoid time-relative words. “Recently,” “the new one,” “the latest fix” rot fast. Use names and versions.

---

Language tips for non-native writers

• Imperative ≠ rude. “Restart the service” sounds like an order in many languages but is the correct, neutral form in technical English.
• Avoid “please” in steps. Runbooks aren’t requests; they’re instructions. “Please restart the service” weakens it.
• Use “should” only for expected outcomes, not actions: “The pod should return to Running” (outcome) vs “Restart the pod” (action).
• Spell out abbreviations once. “Failover (FO)” the first time, then “FO” — but only if you use it repeatedly.

---

Key takeaways

• Write steps in the imperative mood, starting with a strong action verb.
• Choose verbs precisely: drain ≠ purge, roll back ≠ roll out.
• Add “Expected:” success conditions so readers know when a step worked.
• Format decision points as bold if/then branches.
• Make warnings specific and consequence-stating, with ⚠️ used sparingly.

A great runbook turns a panicked 3 a.m. into a calm checklist. Write every step as if the reader is exhausted, scared, and reading it for the first time — because one day, they will be.

Navigating Nuance: Supporting Non-Native Speakers

Writing effective runbooks isn’t just about listing commands; it’s about creating a clear, actionable guide for anyone – regardless of their native language or level of English proficiency. For developers who are still building their professional vocabulary and understanding of common technical phrasing, the directness often found in English can be particularly challenging. It’s crucial to acknowledge that precision isn’t just about accuracy; it’s about conveying intent unambiguously. Consider a recent code review comment you received: “This step lacks detail – what exactly are we checking for?” The subtle implication here is that the reviewer needs more explicit language, perhaps something like, “Verify that the application status is ‘Running’ by querying the health endpoint using curl -s and inspecting the response JSON for a ‘status’ field with a value of ‘Running’.” See how adding that extra detail transforms the instruction from vague to actionable?

Similarly, in Slack conversations related to runbook updates, avoiding overly abbreviated language or jargon is key. Imagine you’re drafting a pull request description: “Updated script for database migration.” That’s insufficient. A more polished approach might be: “Implemented a new script (migrate_db.sh) to perform a full database schema migration, ensuring data integrity and minimizing downtime. This script utilizes psql with appropriate credentials and includes error handling to log any failures.” The expanded description provides context – why the update was necessary, how it’s implemented, and what safeguards are in place. This level of detail isn’t about impressing anyone; it’s about reducing ambiguity for those executing the runbook later.

A common pitfall is using overly complex sentence structures simply to demonstrate authority or technical knowledge. Strive for clarity above all else. When describing a decision point, instead of “If the system fails to respond, then proceed with…” try something like: “If the system does not respond within 60 seconds, escalate to Tier 2 support following established protocols.” The change in phrasing is subtle but dramatically improves readability and reduces potential for misinterpretation. Remember, your goal is to empower others to successfully complete the task, not to showcase your mastery of English.

Finally, proactively offering resources can be hugely beneficial. Consider creating a glossary of frequently used technical terms – particularly those with multiple possible translations – alongside the runbook. A simple phrase like “Refer to Appendix A for a list of key terminology” provides a safety net and demonstrates an understanding of potential communication barriers. Encourage team members to ask questions, and foster a culture where clarification is valued rather than perceived as a sign of weakness.