coleam00 SOP & Runbook Creator
Create practical documentation that people actually follow.
Philosophy
Nobody reads 50-page docs. Make it scannable, actionable, and impossible to misunderstand.
Core principles:
- Scannable - Headers, bullets, tables. No walls of text.
- Actionable - Every step is something you DO, not something you "consider"
- Specific - Numbers, names, thresholds. No "as needed" or "when appropriate"
- Testable - Clear success criteria. How do you know it worked?
- Maintained - Owner, last updated, review schedule
SOP Categories
Pick the right format for your use case:
Tech/Engineering
| Type | When to Use |
|---|---|
| Runbook | Emergency response, incidents, on-call |
| Deployment Playbook | Releases, migrations, maintenance |
| Troubleshooting Guide | Debugging, diagnosis trees |
| How-To Guide | One-off setup, configuration |
| ADR | Architecture decisions |
Operations/Business
| Type | When to Use |
|---|---|
| Process SOP | Repeatable business workflows |
| Checklist | Quality control, verification |
| Decision Tree | Complex if/then scenarios |
| Handoff Doc | Role transitions, shift changes |
Content/Creative
| Type | When to Use |
|---|---|
| Production Workflow | Content creation pipelines |
| Review Process | Approval workflows |
| Publishing Checklist | Pre-launch verification |
General
| Type | When to Use |
|---|---|
| Standard SOP | Any repeatable process |
| Quick Reference | Condensed version of longer SOP |
| Onboarding Guide | New person ramping up |
Universal Structure
Every SOP needs at minimum:
# [What This Does]
> **TL;DR:** One sentence - what, when, who.
## Definition of Done
This is complete when:
- [ ] [Primary outcome]
- [ ] [Verification step]
- [ ] [Any handoff/notification]
## When to Use This
[Trigger conditions]
## Prerequisites
[What you need before starting]
## The Process
[Numbered steps - the actual work]
## Verify Completion
[Return to Definition of Done, confirm all checked]
## When Things Go Wrong
[Common issues and fixes]
## Questions?
[Who to contact]
Definition of Done is the most important section. Put it near the top. Make it a checklist. Be specific.
Writing Rules
Be Specific
| Don't Write | Write Instead |
|---|---|
| "Contact the team" | "Message @sarah in #ops-team" |
| "Wait until ready" | "Wait until status shows 'Complete' (~5 min)" |
| "Review carefully" | "Check items A, B, C in the dashboard" |
| "As appropriate" | "If value > 100" |
| "Regularly" | "Every Monday at 9am" |
| "Soon" | "Within 2 hours" |
Action-First Steps
# Bad
"The report should be reviewed before sending to ensure
accuracy and completeness of all data fields."
# Good
1. Open the report in [System]
2. Verify these fields are populated:
- [ ] Customer name
- [ ] Amount
- [ ] Date
3. Click "Send"
Warnings Come First
# Bad
1. Delete the old records
Note: This cannot be undone
# Good
> **WARNING:** This permanently deletes records. Export first if needed.
1. Delete the old records
Decision Points are Clear
# Bad
"Handle the request based on priority level"
# Good
**If priority is:**
- **Critical:** Drop everything, handle now, notify manager
- **High:** Handle within 4 hours
- **Normal:** Handle within 24 hours
- **Low:** Add to weekly batch
Format Selection Guide
Ask yourself:
- Is this for emergencies? → Runbook
- Is this a complex multi-phase project? → Playbook
- Is this a simple repeated task? → Standard SOP or Checklist
- Does it have lots of if/then branching? → Decision Tree
- Is it for debugging? → Troubleshooting Guide
- Is it recording a decision? → ADR
- Is it for someone new? → Onboarding Guide
Metadata (Keep it Light)
---
title: [Clear name]
owner: [Person or team]
last_updated: [Date]
review_schedule: [quarterly/annually/as-needed]
---
That's it. No document IDs, version matrices, or approval chains unless you actually need them.
Templates
Each template is in references/:
| Template | Use For |
|---|---|
| runbook.md | Incidents, emergencies, on-call |
| standard-sop.md | Any repeatable process |
| how-to-guide.md | One-off tasks, setup |
| onboarding-guide.md | New person ramping up |
| decision-tree.md | Complex if/then flows |
| checklist.md | QC, verification |
All templates have Definition of Done as the primary success criteria.
Quality Checklist
Before publishing:
- Can someone unfamiliar follow this?
- Are all steps actionable (verbs, not descriptions)?
- Are specifics provided (names, numbers, thresholds)?
- Is there a clear "done" state?
- Is the owner/contact info current?
- Has it been tested recently?
Anti-Patterns
Kill these:
- "Per company policy..." (just state what to do)
- "It is recommended that..." (just say "do X")
- "Please ensure..." (just say "check X")
- Passive voice ("the form should be submitted" → "submit the form")
- Describing what to do instead of showing it
- Walls of text with no structure
- Screenshots that will be outdated in a month
Do these:
- Start with the most common path
- Put edge cases at the bottom
- Link to related docs instead of duplicating
- Use tables for reference info
- Use checklists for verification steps
- Include "I'm stuck" escape hatches