SuperAPI AI 工具集

writing-runbooks

写作与研究

查看项目

更新于 10-16 08:01

技能介绍

用途:面向将要被人实际执行的操作文档,包括 runbook、安装与发布流程、故障排查条目、运维检查清单,以及系统里面向操作者的提示字符串。不适用于设计理由说明(应由 writing-design-docs 处理)或无人执行的参考资料;涉及迁移的论证、弃用决策和发布公告分别属于其他文档类型。

主要能力与写法要求:读者常处于事故处理中,因此文档需有序号步骤、每步一个动作、命令可直接复制粘贴,并在显眼处标注危险操作。内容须来自真实运行:每一步都是实际执行过的,每个失败都是真实发生过的;仅想象出来的流程只是草稿。若某分支尚未跑过,需如实标注为草稿并请首位真实执行者反馈;所有分支都没跑过的则整体视为草稿。命令所需的真实值未知时,保留明显的方括号占位符,不得编造,发布前需用真实运行补全,真实性优先于可粘贴性。

结构:标题限定范围,开头说明本文与其他文档的关系及不覆盖的内容;风险不同时在开头给出图例,并应用到每条命令(随时可运行、仅操作者、手工步骤等,可组合)。先给 TL;DR 顺路流程,再按编号分节;命令前给出带版本固定的前置条件及检查命令。每个改变状态的流程都要写明回滚方式,或明确说明不存在回滚及其后果。结尾给出“验证是否成功”一节,说明可观察的最终状态与验证命令;多条路径时标注推荐路径。

故障排查条目:按症状优先编排,给出原始错误字符串、原因与确切修复命令,诊断步骤从成本最低开始,按故障类别分组,深入内容用交叉链接而非内联。

迁移与弃用指南:迁移指南同样按 runbook 要求执行,另有五条规则:以积极方式陈述改动前后对比;映射表是核心产物,逐行对应旧到新的行为、配置键、命令或 API;每一步都要有回滚或说明不可逆;弃用契约必须带日期,说明何时失效、遗留者如何处理、逃生通道在哪;指南自带失效期,迁移完成后由负责人将其标记为历史文档并加取代横幅。

操作者可见字符串:错误信息和日志行阅读窗口最短,修复建议需具体可操作,错误状态要显式可见,不能让流程表面正常。

限制与前提:需具备 technical-writing 技能作为硬性背景;尚未运行过的流程要么先运行,要么标注为草稿;资料未提供具体工具命令、平台或其他实现细节。