技术写作：把复杂概念讲清楚

技术写作的目标不是显得专业，而是让读者在有限注意力里建立正确心智模型，并知道下一步做什么。好文章通常具备：清晰读者画像、可扫读的结构、一个具体例子、以及明确的边界（什么不谈）。

先写大纲，再写句子

推荐结构：场景（为什么在乎）到结论先行，再到分步说明、示例、常见坑与下一步。标题用动词或对象，少用空泛套话。每个二级标题只打一个点，避免在一节里同时讲安装、原理和业绩故事。

类比要可映射

类比是双刃剑：好的类比能降低门槛，坏的类比会误导。使用时写清像在哪里、不像在哪里。例如用集装箱理解隔离与搬运，但不要暗示其中不能再运行复杂系统。

示例胜过形容词

与其说非常简单，不如给出十行可运行的最小例子。代码块保持可复制；标出期望输出。对配置类主题，用错误配置与正确配置对照，比长篇解释更高效。

降低认知负荷的排版

• 一段一个意思；列表承载步骤与清单。
• 专业术语首次出现给一句人话解释。
• 把次要材料放进延伸阅读，正文保持主线。

中文技术写作的两点习惯

尽量少用欧化长句，主语清晰；数字与版本号保持半角，便于复制。截图标注重点，而不是整屏粘贴。若文章教人排障，把环境前提写在最前，能减少一半评论区追问。写完后大声读一遍，凡是自己读着卡壳的句子，读者多半也会卡，把卡壳处拆成两句即可。

修订清单

1. 删掉无法证伪的形容词。
2. 请一位目标读者限时阅读，看他能否复述结论。
3. 检查链接、版本号与截图是否过期。

写作是工程的一部分：文档与代码一同评审，错误率会下降。风动导航的资讯与 Skills 也在实践可扫读与可复制，欢迎投稿你的实践短文。把一篇文章的读者对象写在开头三行里，写作时就不容易跑题。