sop-creator

SOP 与 Runbook 创建器

创建人们真正会遵循的实用文档。

理念

没人会读 50 页的文档。 让文档易于浏览、可执行，并且不可能产生误解。

核心原则：

• 易于浏览 - 使用标题、项目符号和表格。不要写大段文字。
• 可执行 - 每一步都是你要执行的操作，而不是让你“考虑”某件事
• 具体明确 - 写明数字、名称和阈值。不要用“按需”或“适当时”
• 可测试 - 明确成功标准。如何确认操作成功？
• 持续维护 - 记录负责人、最后更新时间和审查计划

SOP 类别

根据使用场景选择合适的格式：

技术/工程

类型	使用场景
Runbook	应急响应、事故、值班
部署操作手册	发布、迁移、维护
故障排查指南	调试、诊断流程
操作指南	一次性设置、配置
ADR	架构决策

运营/业务

类型	使用场景
流程 SOP	可重复的业务工作流
检查清单	质量控制、验证
决策树	复杂的条件判断场景
交接文档	角色交接、班次交接

内容/创意

类型	使用场景
制作工作流	内容创建流程
审查流程	审批工作流
发布检查清单	发布前验证

通用

类型	使用场景
标准 SOP	任何可重复的流程
快速参考	长篇 SOP 的精简版本
入职指南	帮助新人快速上手

通用结构

每份 SOP 至少需要包含：

# [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]

完成定义是最重要的部分。 将其放在靠前的位置。将其写成检查清单，并明确具体要求。

写作规则

明确具体

不要这样写	改为这样写
“联系团队”	“在 #ops-team 中给 @sarah 发消息”
“等到准备就绪”	“等待状态显示为‘Complete’（约 5 分钟）”
“仔细检查”	“在仪表板中检查 A、B、C 项”
“视情况而定”	“如果值 > 100”
“定期”	“每周一上午 9 点”
“尽快”	“在 2 小时内”

步骤以行动为先

# 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"

先写警告

# 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

明确决策节点

# 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

格式选择指南

问问自己：

1. 这是用于紧急情况的吗？ → Runbook
2. 这是一个复杂的多阶段项目吗？ → 操作手册
3. 这是一个简单且重复的任务吗？ → 标准 SOP 或检查清单
4. 其中有很多条件分支吗？ → 决策树
5. 这是用于调试的吗？ → 故障排查指南
6. 这是用于记录决策的吗？ → ADR
7. 这是给新手用的吗？ → 入职指南

元数据（保持精简）

---
title: [Clear name]
owner: [Person or team]
last_updated: [Date]
review_schedule: [quarterly/annually/as-needed]
---

就这些。除非确实需要，否则不必添加文档 ID、版本矩阵或审批链。

模板

每个模板都位于 references/ 中：

模板	用途
runbook.md	事故、紧急情况、值班
standard-sop.md	任何可重复的流程
how-to-guide.md	一次性任务、设置
onboarding-guide.md	帮助新人快速上手
decision-tree.md	复杂的条件判断流程
checklist.md	质量控制、验证

所有模板都将完成定义作为首要成功标准。

质量检查清单

发布前：

• 不熟悉此流程的人能否照着完成？
• 所有步骤是否都可执行（使用动词，而非描述）？
• 是否提供了具体信息（名称、数字、阈值）？
• 是否明确说明了“完成”状态？
• 负责人/联系信息是否为最新？
• 最近是否测试过？

反模式

杜绝这些做法：

• “根据公司政策……”（直接说明该怎么做）
• “建议……”（直接说“执行 X”）
• “请确保……”（直接说“检查 X”）
• 使用被动语态（“应提交表单” → “提交表单”）
• 只描述该怎么做，而不提供示例
• 没有结构、冗长难读的文字
• 放上一个月后就会过时的截图

这样做：

• 从最常见的操作路径开始
• 将边缘情况放在末尾
• 链接到相关文档，而不是重复内容
• 使用表格呈现参考信息
• 使用清单列出验证步骤
• 提供“我卡住了”的求助途径