技术文档写作：五步流程、可执行步骤与文档不烂尾的机制
技术文档写不好，最常见的表现是「写得很全，但没人看得懂」。原因往往不是语言能力，而是把它当成了「产品介绍」在写——先讲背景、再讲架构、最后才讲怎么用。
技术文档只有一个验收标准：一个没接触过这个功能的人，照着文档能不能一次把任务做完。本文按这个标准给四类文档的写法差异、五步写作流程、步骤与代码示例的硬要求，以及文档随代码更新的落地机制。
先分清四种文档，别混着写
同一份文档里混进教程、参考和概念解释，读者就会迷路。四类文档的任务完全不同：
| 类型 | 读者状态 | 写法 | 不该出现的内容 |
|---|---|---|---|
| 教程 | 完全不会，想学会 | 一步一步带做，每步都有可见结果 | 完整的参数表、边界情况 |
| 操作指南 | 会一点，要完成任务 | 按目标组织，最短路径 | 原理长篇解释 |
| 参考手册 | 熟练，要查细节 | 结构化、可搜索、每条独立 | 教学式铺垫 |
| 概念说明 | 想理解为什么 | 讲模型、关系、取舍 | 操作步骤 |
判断方法看读者的问题：他在问「怎么开始」是教程，「怎么做 X」是操作指南，「这个参数什么意思」是参考，「为什么要这样设计」是概念。一个页面只回答一类问题。
五步写作流程
文档不是「想起来就写」，按这五步走，返工最少：
- 定任务：用一句话写出读者读完后能做成什么，动词开头。写不出这句，说明这个页面不该存在。
- 写前置条件：账号权限、依赖版本、已完成的步骤、需要的数据。这一节省掉，后面 80% 的求助都来自这里。
- 拆步骤：一步一个动作，每步都能被执行和验证。编号连续，不要嵌套超过两层。
- 写验证：每段操作后给一个「你应该看到什么」。没有验证点的步骤，等于没写完。
- 写失败处理：这一步最常出的三个错、错误信息原文、以及对应的处理动作。
步骤要写成可执行的动作
步骤是技术文档的主体，也是最容易写虚的部分。对照下面这张表改一遍，可执行性会明显提升：
| 坏步骤 | 问题 | 改成 |
|---|---|---|
| 配置好环境变量。 | 配哪些、配在哪、什么格式都没说 | 在项目根目录新建 .env，写入 API_KEY=你的密钥，保存后重启服务 |
| 根据需要调整参数。 | 没有任何判断依据 | 并发低于 100 时用默认值 4；高于 100 改为 CPU 核数的一半 |
| 安装依赖。 | 不知道用哪个包管理器、什么版本 | 在项目根目录执行 composer install，需要 PHP 8.2 以上 |
| 确认服务已启动。 | 没有验证方式 | 浏览器打开 http://localhost:8080/health，应返回 {"ok":true} |
三条硬规则：一步一个动作、命令单独成行可直接复制、每一步有可观察的结果。超过三个动作的步骤，拆开。
代码示例的三个要求
- 可复制即运行：不留
...省略号，不留「你的密钥」以外的占位符；占位符统一用尖括号并说明。 - 最小可运行：只保留说明问题所需的行，其它一律删掉。示例越短，读者越敢改。
- 带预期输出：代码块下面紧跟一段输出示例，读者能立刻判断自己是否成功。
示例里的格式化细节（行内代码、标点、空格）同样影响可读性，中文与英文、数字之间加空格的规则见中文排版规范；示例与说明文字混排时，Markdown 的标题层级与代码块写法见Markdown 语法入门。
用词：把「形容词」换成「条件」
技术文档里最该删的是模糊动词和评价性副词。常见替换：
| 不要写 | 改成 |
|---|---|
| 支持多种格式 | 支持 JSON、CSV、XLSX 三种格式 |
| 快速返回结果 | 单次请求在 200ms 内返回（10 万行以内数据集） |
| 建议使用最新版本 | 使用 2.4 及以上版本，2.3 不支持该参数 |
| 可能会出现异常 | 令牌过期时返回 401，需重新获取 |
| 请合理设置超时 | 超时设为 30 秒；批量任务按每 1000 条加 10 秒 |
另外两个习惯很有用：一句话不超过 40 字；同一概念全文只用一个词，不要「令牌」「Token」「凭证」混用。
错误处理段落怎么写
读者真正需要文档的时刻，往往是他遇到报错的时候。这一节按固定四段写：
- 错误现象：贴出报错原文（代码块），不要改写。
- 原因：一句话说清触发条件，例如「请求头缺少 Authorization」。
- 处理：给可执行的修复动作，按可能性从高到低排。
- 仍不解决：给下一步（查日志的路径、需要提供的信息、支持渠道）。
把最常见的三个报错放在页面底部，比写一段「如遇问题请联系我们」有用得多。
怎么验证文档是有效的
写完自己读一遍没用，做一次 20 分钟的走查：
- 找一个没参与该功能开发的同事，只给他文档，不给口头提示。
- 让他完成任务，你只记录：在哪一步停了超过 1 分钟、问了什么问题、看错了哪句话。
- 把停顿点按出现顺序修掉，优先修「前置条件」和「验证方式」。
- 修完再找另一个人走一遍，两次都通过才算可用。
这套方法和写长文的流程是相通的：先定读者任务，再排信息顺序，最后做验收。长文的结构安排可以参考长文写作流程。
让文档跟着代码一起更新
文档失效的原因几乎都是「改了代码没改文档」。四个低成本机制：
| 机制 | 做法 | 成本 |
|---|---|---|
| 同仓同 PR | 文档与代码放同一仓库，改动涉及界面或接口时，PR 模板里勾选「已更新文档」 | 低 |
| 示例即测试 | 文档里的命令与代码片段进入 CI，跑不过就拦住合并 | 中 |
| 版本标注 | 每个页面标注适用版本，过期页面直接标「已废弃」并指向新页 | 低 |
| 反馈入口 | 每页底部一个「这页有帮助吗」按钮，差评自动建 issue | 低 |
四个里至少做「同仓同 PR」和「反馈入口」，否则文档会在三个月内自然腐烂。
常见问题
文档要写给谁看？
每个页面只写给一类人。入门教程假设零基础，参考手册假设读者已经会了。试图在一页里同时服务新手和专家，结果是两边都读不下去。
要不要写「原理」？
操作指南里不写，单独开概念页，然后在步骤里加一句「原因见…」。读者要的是完成任务，不是在上手阶段理解架构。
截图要放多少？
界面会变，截图会过期。原则是：文字能说清的不用图；必须用图的地方，图里不要带会变的细节（版本号、时间、用户名）。
中文技术文档最容易犯的错是什么？
把「主谓宾齐全的短句」写成「长定语套长定语」。其次是中英文混排缺空格、全角半角混用。这两类问题最影响阅读速度。
一个人维护文档，怎么保证不烂尾？
只维护「被问到最多的十个页面」，其余标记为社区维护。文档质量靠优先级，不靠意志力。
小结
技术文档不是把功能讲清楚，而是把任务交出去：一句可验收的目标、一段前置条件、一串能照做的步骤、一个验证点、三个常见错误的处理。写完让新人走一遍，卡住的地方就是下一篇要改的地方。