技术文档常见文章结构
写技术文档时，选对结构比堆砌内容更重要。结构决定了读者的阅读路径：他是来”解决一个问题”，还是来”理解一件事”，抑或是来”做一个决定”。下面按读者意图归纳常见结构。
一、结构速查表
| 结构 | 段落骨架 | 适用场景 |
|---|---|---|
| 问题解决型（最通用） | 背景 → 方案 → 实现 → 验证 → 总结 | 具体技术问题的解法记录，如「如何把 List 传给可变参数方法」 |
| 概念科普型 | 是什么 → 为什么 → 怎么做 | 术语与原理入门，如「什么是 CAS」「什么是 NPE」 |
| 排错复盘型 | 现象 → 定位过程 → 根因 → 修复 → 预防 | 线上故障复盘、Bug 排查笔记、FAQ |
| 并列清单型 | 结论先行 + 若干平级要点 | 编码规范、最佳实践、速查表，如「设计模式的七大原则」 |
| 教程步骤型 | 前置条件 → Step 1..N → 验证 → 下一步 | Quick Start、安装部署、操作手册 |
| 选型对比型 | 需求 → 候选方案 → 对比维度 → 结论 → 风险 | 技术选型、调研报告，如「Redis vs Memcached」 |
| 参考手册型 | 签名 → 参数 → 返回值 → 异常 → 示例 | API/SDK 文档、命令行工具手册 |
| 源码深挖型 | 用法 → 原理 → 源码走读 → 实践启示 | 框架原理分析、源码系列 |
| 结论先行型（金字塔） | 结论 → 依据 → 论据 → 行动项 | 汇报、RFC/ADR、评审材料 |
| 设计文档型 | 需求 → 架构 → 详细设计 → 风险/容量 → 演进 | 系统设计、模块详细设计 |
二、各结构要点
1. 问题解决型
最常用、也最容易被写成流水账。关键是先给可复制的答案，再讲原理：
- 背景：说清约束条件（版本、环境、为什么不能直连）；
- 方案：一句话给出做法；
- 实现：最小可运行示例；
- 验证：给出预期输出或反例；
- 总结：提炼成可记忆的结论清单。
2. 概念科普型
顺序不能反。先”是什么”（给定义与一句话类比），再”为什么”（解决什么问题、不解决什么问题），最后”怎么做”（用法与边界）。避免上来就贴大段源码。
3. 排错复盘型
价值在于过程，而不是结论。必须保留时间线、关键日志、被排除的错误假设，并在最后落到”如何预防”（监控、单测、代码约束），否则只是换个地方再犯。
4. 并列清单型
要点之间必须同层级、无重叠（MECE）。每条保持相同句式，便于扫读；长篇内容应再按维度分组加小标题。
5. 教程步骤型
铁律：每一步都要可验证。给出前置条件、完整命令、预期输出，以及”失败了怎么办”。步骤中的版本号、路径要写死，避免”最新版”这类随时间失效的表述。
6. 选型对比型
必须给出明确的对比维度与权重（性能、一致性、运维成本、生态、团队熟悉度），并给出结论与适用边界。”各有优劣，视情况而定”等于没写。
7. 参考手册型
以查阅效率为第一目标：结构固定、信息密度高、每个参数都要有默认值与取值范围，示例必须能直接复制运行。
8. 源码深挖型
从”看得见的用法”进入”看不见的实现”，再回到”对落地的启示”。引用源码要标注类名、方法与版本，避免脱离版本谈实现。
9. 结论先行型
面向决策者，首屏就要有结论与行动项。背景与数据只作为支撑放在后面。
10. 设计文档型
除架构与详细设计外，务必包含风险、容量估算与演进路线，这是区分”设计”与”实现说明”的地方。
三、如何选择
按读者的第一意图判断：
- 读者要解决一个具体问题 → 问题解决型；
- 读者要理解一件事 → 概念科普型 / 源码深挖型；
- 读者要照着做一遍 → 教程步骤型；
- 读者要做决定 → 选型对比型 / 结论先行型；
- 读者要查阅细节 → 参考手册型；
- 读者要复盘或评审 → 排错复盘型 / 设计文档型。
小结
结构服务于读者意图。动笔前先回答一个问题：读者读完这篇文章后要做什么？ 答案决定了骨架，内容只是填充。