技术写作与文档2020transposit.com
身为 SRE，如何撰写运维手册文档
Writing Runbook Documentation When You’re an SRE
导读
这篇博文讲 SRE 该怎么写 runbook（操作手册）文档，评论区则围绕它展开了相当实用的争论：有人给出具体的排版与命令写法建议，有人分享把文档代码块做成可执行脚本、从而让文档与代码保持同步的方案，还有人直接主张 runbook 是反模式、能写成脚本的就不该写成文档。对写作者来说，这是一次关于“操作类文档到底该怎么写、写到多细”的实战讨论。
可以直接用的写作要点
- 01
操作类文档尽量放在单页内，并为每节铺足够的关键词，让读者在链接失效时也能靠搜索找到对应步骤。
- 02
把命令放进高亮代码块而不是句子中间，变量用 $HOST 这类可替换写法，并配好示例输入与预期输出，方便别人复制粘贴后改参数。
- 03
文档要精简到最低限度：能用脚本完成的多步操作，优先改成脚本，而不是写成给人类读的步骤说明。
- 04
文档最大的敌人是过时，需要考虑让文档与代码/脚本保持同步的机制，否则再漂亮的 runbook 也很快失真。
HN 评论精选
把 runbook 放在单页并铺满关键词，命令放进代码块并用 $HOST 式的变量写法，配上示例输入和输出。
这篇文章写得不算好，以下是几点改进建议：1）runbook 过时得比任何东西都快，所以务必把整本放在一个页面上，让告警能指向具体小节，并在每节里塞满关键词，这样链接失效时用户和新人也搜得到；2）把相关告警（比如“主机 xyz 挂了”）归到同一节，每个可能的 xyz 各设一个小节标题；3）把命令行命令放进 shell 或代码高亮框里（绝不能写在句子中间），变量用 $HOST 这类写法而不是 <host>，事先给出示例值和运行后的示例输出，也不要用可复制的 $ 当提示符——这样别人复制粘贴时最容易改参数，也知道该期待什么结果；4）用小号链接列出所有相关控制台，包括过去问题的历史视图；5）小节模板可以是：定义（如“25% 主机在过去 10 分钟平均处于宕机”）、严重程度……
williamDafoe查看英文原文
This is not a very good article. Here are some improvements. 1. Runbooks go out of date faster than anything. Therefore it is absolutely crucial to have the whole book on a single page and alerts vector to the proper subsection. Also pepper each section with a good set of keywords. This will allow users and newbies to easily search for procedures or related alerts when links invariably break. 2. Group related alerts ("host xyz down") in a single section with many section titles. One for each possible xyz. 3. Go ahead and put commandline commands in the runbook, in shell-command or code highlighted boxes (NEVER inside sentences). User defined fields should be delineated with $HOST etc (never <host>) and sample values for the vars given beforehand with sample output afterward. Never use a copyable $ to delineate shell commands. This creates the best possible user experience for people reusing your commands by cut and paste so they can more easily change values and so they know what to expect. 4. Link all relevant consoles in very small links (CPU usage in clusters: ym qf ij) including historical links to console views for past problems and how they look. 5. Section templates might look like this: 1.8. Too many cacheservers are down 1.8.1 Definition. This means that 25% of the hosts (on average) have been down over the past 10 minutes 1.8.2 Severity. Our load balancer will route all requests to surviving hosts and clients will retry on timeout so normally this is not severe (there is only a performance impact). However it could cascade due to RAM exhaustion or a query-of-death or due to a config push of broken software so assess the service right away for these problems. 1.8.2 Remediation ... Rollback or resource scaling or bypassing the cache service on the command line ... - Google search SRE
把文档里的代码块做成可执行、参数化的脚本，能让文档和代码保持同步，但代价是带来安全风险。
我在公司内部做过类似的东西：写一个解析 markdown 目录的应用，但代码块是可执行的。代码块前半部分用 YAML 描述输入参数，后半部分是真正的 shell 代码；代码块下方会出现“运行”按钮，点击后按参数定义生成输入界面，然后在 kubernetes 里起一个 pod 执行脚本，脚本还能通过 Vault 获取密钥。把 runbook 链接放进 PagerDuty 告警里，文档和代码就能保持同步，体验很好。但这也相当于给整个基础设施开了 shell 后门（因为它有 Vault 权限），我尽力防护了仍然不安心；可没有它，我真不知道怎么让代码和文档保持同步。
kureikain查看英文原文
I have been using this at work internally. Basically I write an app that parse a directory of markdown file. However, the code block is runnable. The code block is organize like this: ``` input: - name: description: - othervar: description: --- real shell code here ``` It adds a run button under the code block, when run, it parse the inputs to generate UI for input these parameter. Then it spin up a pod in kubernetes and run the script. We are already using Vault, so the script can access vault to get the secret it wants. It feels awesome because we put the link to runbook in pagerduty alert. It keeps the document and code in-sync. However, it's a kind of like a backdoor :-(. It essentially give shell access to entire infrastructure(Since it has Vault access). I tried hard to protect this tool but still feel uneasy about it. But without it I don't know how hard it is to keep code and document in-sync.
能写成脚本的多步操作就不该写成 runbook，文档应精简并由编辑删减，凡是能自动化的都自动化。
Runbook 更像是反模式。“执行 X 的命令清单”其实就是一个脚本，或者本该是脚本。如果完成一件事需要不止一步，那说明自动化或可编程性不够，这才是该修的问题，而不是教开发怎么写散文。代码能快速、相对容易地测试，文档不能。文档应该尽量精简，比如“# 服务器 ## 重启 - ./scripts/server/reboot.sh”。开发写的东西应该由编辑过一遍，删到最低限度；典型的 readme 充满废话，而且其中真正的干货一半以上是错的。一切都要自动化。
epicgiga查看英文原文
Runbooks are more of an anti-pattern than anything. A list of commands you should run to accomplish X -> that's a script. Or it should be. If accomplishing a task takes more than a single step, it means there's insufficient automation or programmability, and that's the problem you should fix, not teaching devs how to be better writers of prose. Code can be tested quickly and relatively easily. Docs can't. Docs should be as minimal as possible: "# Server ## Rebooting - ./scripts/server/reboot.sh". Any docs written by a dev should be run by an editor, who should strip them down to the bare minimum. Your typical readme is inundated with waffle, and the actual meat in it is wrong well over half the time. Automate everything.
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选