技术写作是工程师最被低估的复利技能。同样一个分布式系统或一段踩坑复盘，写得好能让读者十分钟读懂，写不好则三个月后连自己都看不懂。更重要的是，写作会倒逼你把模糊的理解厘清——你以为懂了，一动笔才发现逻辑有洞。本文不谈文笔，只讲一套可复用的结构化方法：从定读者、搭骨架，到模板、清单，帮你把每一次技术输出都沉淀成可检索、可复用的资产。
很多团队重代码、轻文档，结果知识全锁在几个人脑子里。一旦有人离职或项目交接，新成员要从零重踩一遍坑。把技术写作当成工程实践的一部分，本质上是在给团队买”认知保险”：一次写清楚，十次被搜到，百次被复用。
一、动笔前先定读者与目的
读者是谁
动笔前先回答两个问题：这篇给谁看？他读完要能做什么？给新人的入门文和给架构师的决策文，结构与术语密度完全不同。把读者画像写在一张便签上，写作时时刻对照，避免一会儿解释基础概念、一会儿又默认你都懂。一个实用的判断标准：如果你的读者是”三个月前的自己”，那这篇就写对了。
一篇文章只回答一个问题
贪多的文章往往两头不讨好。与其写《从零到一的微服务大全》，不如拆成《服务注册为什么选 Consul 而非 Eureka》《灰度发布到底怎么做》。聚焦一个问题、结论先行，读者才愿意读完，搜索引擎也更容易把你的单篇命中长尾词。拆分后的小主题还更容易排期，每周稳定产出一两篇，比憋一篇万字长文更可持续。
二、用倒金字塔搭骨架
新闻写作的”倒金字塔”同样适用于技术文：最重要的结论放最前，细节往后排。读者扫一眼开头就知道值不值得读，移动端也更友好；搜索引擎抓取摘要时也能更快命中关键词。下面是一份我常用的骨架模板，动笔前先把这六格填满，再往里填肉。
# 文章骨架模板
1. 钩子（Hook）：一个痛点或反直觉的事实（1–2 句）
2. 结论先行：直接给出本文答案 / 建议
3. 背景：谁、在什么场景下遇到什么问题
4. 方案：分步骤，每步配代码或图
5. 对比 / 权衡：为什么这样做而非那样
6. 小结与延伸阅读三、四类常见技术文及其写法
技术写作不是一种文体，而是一类。先想清楚你写的是哪一类，结构自然就出来了。下面这张表是我长期分类后的小结。
| 类型 | 典型场景 | 结构要点 |
|---|---|---|
| 教程 / How-to | 教人装环境、跑通 Demo | 目标前置、步骤可复制、给出预期输出 |
| 复盘 / Postmortem | 线上事故、踩坑记录 | 时间线、影响面、根因、改进项 |
| 选型 / 对比 | 技术决策、框架横评 | 维度表、权衡、明确结论 |
| 原理 / 深度 | 吃透一个机制 | 由浅入深、配图、可被验证 |
四、可复用的技术文档模板
把常用结构固化为模板，每次只填空，能大幅降低启动成本。下面是一份 Markdown 模板，配合 front matter 记录元信息，既能直接发布，也能进 Git 管理，还能和 CI 联动做校验。
---
title: 技术写作实战
slug: tech-writing-practical
tags: [技术写作, 文档, 工程效率]
status: publish
---
## 背景
（谁、在什么场景下遇到什么问题）
## 现象
（可复现的步骤 / 关键报错，贴关键日志）
## 根因
（用一句话讲清背后的机制）
## 解决
（分步骤，命令与代码贴全，确保可复制）
## 验证
（如何确认问题已解决）
## 复盘
（下次如何避免 / 可迁移的经验）五、让代码与图表替你说话
能贴代码就不要只描述，能用表就不要只堆段落。同样讲”如何排查慢查询”，贴一段 EXPLAIN 输出比写三段形容词更有用。下面的对比说明两种写法之差：展示型写法降低读者脑内还原成本，也方便他自己复制改造。
| 写法 | 读者理解成本 | 可复用性 |
|---|---|---|
| 纯文字描述步骤 | 高（需在脑中还原） | 低 |
| 贴完整命令 / 代码 | 低（复制即跑） | 高 |
| 配架构图 / 时序图 | 中（一眼看懂全局） | 中 |
一个实用的”描写改展示”练习：把你文中所有”然后系统就会……”这类模糊句，替换成一段可执行的命令或一张状态对比表。改完通常会发现，你原本以为讲清楚了，其实漏了关键前提。
六、标题与 SEO：让对的读者找到你
好内容也需要好标题才能被搜到。技术读者多用长尾词检索，标题里埋准关键词，比追求吸睛重要得多。下面几种标题模式在行业内验证过转化，可按场景选用。
| 模式 | 示例 | 适合 |
|---|---|---|
| 问题式 | 为什么 Kafka 消费会重复？ | 排错、原理 |
| 实战式 | Docker 多阶段构建实战 | 教程 |
| 对比式 | PostgreSQL vs MySQL 选型 | 选型 |
| 清单式 | 上线前必查的 10 项 | 复盘、规范 |
七、发布前对照清单
提交前过一遍清单，能挡掉大部分返工。这六条也是我每次发文的自检项，养成习惯后几乎不再出现”发完才发现忘了内链”的尴尬。
| 检查项 | 是否完成 |
|---|---|
| 标题含核心关键词、≤30 字 | ☐ |
| 首段 150 字内出现关键词 | ☐ |
| 至少 1 处内链指向相关旧文 | ☐ |
| 代码可复制、命令真实可用 | ☐ |
| 图片有 alt 描述、无版权风险 | ☐ |
| 结论先行、文末有小结 | ☐ |
八、把写作纳入工程流程
技术写作不该是项目结束后的”额外工作”，而应和代码一起进入流程。把文档放进 Git，用 CI 做链接校验与拼写检查（参见《文档即代码：用 Git 与 CI 管理技术文档》）；写完请同事做一次”文档评审”，像审代码一样挑逻辑漏洞（参见《代码评审实战指南》）；想积累好素材，平时多读优秀开源项目的源码与 README（参见《阅读开源源码的实战方法》）。写作和编码一样，都是可被训练、可被复用的工程能力——今天写下的每一篇，都是在给未来的自己减负。
相关阅读：文档即代码：用 Git 与 CI 管理技术文档 · 代码评审实战指南 · 阅读开源源码的实战方法
