大多数开发者写的比他们意识到的要多。代码注释、提交信息、拉取请求描述、内部文档、解释架构决策的 Slack 消息、事件复盘报告、README 文件、API 文档，有时甚至是博客文章或会议提案。在软件工程中，写作不是次要活动，而是主要活动，然而很少有开发者刻意投入时间去提升写作能力。
我招聘和指导开发者已有十多年，我可以告诉你，清晰表达的能力是职业发展轨迹中最可靠的预测指标之一。不是因为写作比编码更受重视，而是因为能够清晰表达复杂想法的开发者往往是那些能设计出更好的系统、带领更高效的团队、构建用户真正理解产品的开发者。
本文是一份实用指南，旨在帮助你全面提升技术写作能力，从代码级文档到面向公众的内容。没有冗余内容，没有文学理论，只有框架、常见错误和你可以明天就应用的具体建议。
为什么技术写作比你想象的更重要
技术写作的价值主张不是抽象的，它会在你的职业生涯中以具体、可衡量的方式体现出来。
他人可以维护的代码
最直接的影响体现在你的代码库上。文档完善的代码是可维护的代码。一个有清晰注释的函数，解释了它存在的原因、处理的边界情况以及所做的假设，当包括未来的你在内的某人在六个月后需要修改它时，可以节省数小时的考古时间。
反之亦然。没有文档，或者更糟的是，有误导性文档的代码，是一种维护负担。我曾目睹团队花费整天的时间来反向工程业务逻辑，而这两段注释就能解释清楚。这不是文档问题，而是生产力问题，而且这个问题会随着时间的推移而累积。
职业可见度和影响力
写作好的开发者有着不成比例的影响力。当你写一份清晰的技术提案时，决策者才能真正评估你的想法。当你写一份详细的事件复盘报告时，整个团队都能从失败中学习。当你发布一篇关于你解决问题的博客文章时，你建立的专业声誉会超越你当前的雇主。
相反，沟通不畅的绝妙想法往往会悄无声息地消亡。我曾看到优秀的工程师因为无法以书面形式清晰表达他们的想法而一直被忽视领导职位。想法是有的，但沟通不到位，没有人有时间去挖掘埋藏在混乱文字下的才华。
异步协作
在分布式团队和异步工作流程的时代，写作是协作的主要媒介。你的 Slack 消息、你的拉取请求审查、你的设计文档：这些都是你的同事与你共事的方式。清晰、深思熟虑的写作让你更容易合作。模糊或杂乱的写作会产生摩擦、误解和不必要的来回沟通。
编写代码注释：解释为什么的艺术
代码注释是最常见的技术写作形式，但也最容易被做得糟糕。基本原则很简单：注释应该解释为什么，而不是做什么。
好的注释是什么样的
重述代码功能的注释是噪音。如果代码是 count += 1，说”将计数加一”的注释没有添加任何信息。但是解释”我们在检查阈值之前增加计数，因为下游 API 从 1 开始计数，而不是从 0 开始”的注释告诉了读者一些仅从代码本身无法推断出的信息。
好的注释分为几类。意图注释解释为什么选择特定方法而不是替代方案。约束注释记录影响代码的外部要求或业务规则。警告注释标记非明显的陷阱、性能影响或脆弱的依赖关系。上下文注释提供相关问题、规范或设计文档的链接。
测试注释是否有用的实用方法：如果你删除了注释，一个有能力的开发者第一次阅读代码时是否可能会误解某些内容、做出错误的假设或浪费时间调查？如果是，那么这个注释就发挥了作用。
代码注释中的常见错误
注释一切。 过度注释会产生噪音，掩盖真正重要的解释。如果每一行都有注释，那么没有一条会显得重要。要有选择性，在代码不明显或推理需要保留的地方进行注释。
让注释腐烂。 过时的注释比没有注释更糟糕，因为它们会主动误导。当你更改代码时，更新或删除相关的注释。与代码矛盾的注释会造成混乱，并削弱对所有注释的信任。
使用注释作为清晰代码的替代品。 如果你的代码需要大量注释才能被理解，考虑代码本身是否可以重构为自解释的。更好的变量名、提取的辅助函数和简化的逻辑通常可以消除对解释性注释的需求。
提交消息和拉取请求描述
版本控制历史是一种长期文档形式。六个月后，当你试图理解为什么做出特定更改时，提交消息和 PR 描述是你获取上下文的主要来源。
编写有效的提交信息
标准格式行之有效是有原因的：简洁的主题行不超过50个字符，概述变更内容，后跟一个空行，然后是解释动机和上下文的正文。主题告诉你改变了什么，正文告诉你为什么改变。
像”修复bug”这样的主题没有提供任何有用信息。而像”防止超时重试时重复的webhook传递”这样的主题则明确告诉你修复了什么以及为什么修复。三个月后，当你浏览提交历史以理解行为变更时，这种具体性是无价的。
在正文中，回答这些问题：这个变更解决了什么问题？为什么选择这种方法而不是其他替代方案？是否有任何副作用或后续工作需要完成？审查者应该注意什么？这会将提交信息从一个标签转变为有用的工件。
加速审查的拉取请求描述
一份精心编写的PR描述是对审查者的礼物。它设定上下文，引导他们关注变更的重要部分，并降低理解差异的认知负担。
我建议对非平凡的PR使用结构化格式。首先用一两句话总结PR的内容和目的。然后描述方法，解释关键设计决策以及你考虑过的任何替代方案。包含测试说明：你测试了什么，如何验证变更，以及你担心的任何边缘情况。最后，指出任何后续工作或已知限制。
这种结构改变了审查过程。审查者不再需要盯着差异并试图重构你的推理，而是从上下文开始，可以根据你陈述的意图来评估实现。审查变得更快、更专注、更高效。
内部文档：设计文档和ADR
内部文档，包括设计文档、架构决策记录和运行手册，是技术写作杠杆最高但平均质量最低的地方。
设计文档
设计文档在实现之前捕获重要技术决策背后的推理。目标不是产生正式规范，而是在投入工程时间之前清晰地思考问题并获得团队的反馈。
有效的设计文档共享一个共同结构。它们从问题陈述开始：当前情况如何，有什么问题，我们试图实现什么。它们提出足够详细的建议解决方案，使读者能够理解方法并评估其权衡。它们明确列出考虑过的替代方案及其被拒绝的原因。它们还确定风险、未解决的问题和成功标准。
设计文档中最常见的错误是在没有充分定义问题的情况下直接跳到解决方案。如果读者不理解当前状态为何不足，他们就无法有意义地评估你的提案。在问题描述上至少应与解决方案描述投入同等的精力。
架构决策记录
ADRs是一种记录架构决策及其背景的轻量级格式。每个ADR捕获一个单一决策：决定了什么，为什么决定，考虑了哪些替代方案，以及预期的后果是什么。
ADRs的力量在于它们的累积效应。记录一年中的重要决策后，你就拥有了架构演化的可搜索历史。新团队成员不仅能了解系统的外观，还能理解它为何呈现这种形态。这避免了质疑过去决策然后尝试重新设计却重新发现相同约束的循环。
保持ADRs简短和事实性。典型的ADR应在两到三分钟内可读。目标是捕获背景，而不是撰写全面分析。如果决策需要广泛分析，那应该放在设计文档中，ADR作为摘要和参考链接到它。
为外部受众写作：博客文章和教程
面向公众的技术写作、博客文章、教程和文档遵循与内部写作不同的规则。读者与你没有共享背景。他们通过搜索引擎或社交媒体找到你的内容，如果你不能快速证明你能提供有价值的内容，他们就会离开。
倒金字塔结构
新闻业的倒金字塔结构对技术博客文章非常有效。把最重要的信息放在前面：问题是什么，解决方案是什么，读者为什么应该关心。然后按重要性递减的顺序提供支持性细节。
许多开发者按时间顺序撰写技术文章，叙述他们的探索之旅。这将有用的信息埋藏在读者未要求的叙述之下。倒过来。从解决方案或见解开始，然后为想要理解探索过程的读者补充背景信息。
解释框架
对于解释性内容，我使用一个四步框架，它始终能产生清晰的技术写作。
第一步：说明你要解释的内容以及读者为什么应该关心。一到两句话。这是你的钩子。
第二步：提供心智模型。在深入细节之前，给读者一个理解主题的概念框架。一个类比，一个简化的图表，或者各部分如何组合在一起的高级描述。这个心智模型是他们将后续细节附着的支架。
第三步：详细说明。现在提供具体内容：代码示例、配置、分步流程。在过程中参考你的心智模型，将每个细节与整体图景联系起来。
第四步：处理边缘情况和陷阱。什么可能出错？有什么限制？读者应该注意什么？这是你真实世界经验最能增加价值的地方，也是你的内容与仅涵盖理想路径的文档有所区别之处。
技术博客中的常见错误
假设过多背景信息。读者并不与你共享相同的心智模型、代码库或你对主题的历史了解。提供更多背景信息而非更少是更稳妥的做法。你可以使用渐进式披露，将高级细节放在读者可以跳过的子标题下，而不是完全省略背景信息。
编写教程却不解释原因。一个只告诉你运行命令而不解释其作用的教程无法教授任何持久性的知识。读者按照步骤操作，得到结果，却学不到可转移的知识。包含每个步骤的简要解释，这样读者在获得输出的同时也能建立理解。
代码埋得过深。在技术文章中，代码示例是读者想要的内容。把它们放在最显眼的位置。不要让读者费力读完五段文字才能找到回答他们问题的三行代码。先展示代码，然后进行解释。
不够无情地编辑。初稿总是太长。每篇技术文章都受益于一次修改，删减不必要的句子、简化复杂表达、移除离题内容。如果一个段落不能直接服务于读者的目标，就删除它。你的读者很忙，尊重他们的时间。
能产生复利效应的实用写作习惯
提升技术写作能力不在于学习语法规则或阅读风格指南，而在于建立习惯，使清晰写作成为你的默认模式。
先写作，后编辑
写作的最大障碍是试图在第一遍就写出完美的文章。将记录想法的创造性活动与完善想法的分析性活动分开。先写一个不考虑质量的草稿，然后再将其编辑成型。这种两步法比试图一次性写出精炼的文章更快且效果更好。
大声朗读你的文章
大声朗读你的文本是我所知最有效的编辑技巧。当你听到它们时，别扭的措辞、冗长的句子、缺失的过渡和不清晰的解释会立刻显现。如果你在朗读一个句子时结巴，你的读者也会同样困惑。重写直到文章流畅为止。
使用具体示例
当抽象的解释与具体的例子相结合时，就会变得清晰。与其抽象地描述一个概念，不如展示它在特定场景中的应用。说”最终一致性意味着不同节点可能返回不同的值”是抽象的。而说”用户A更新了他们的个人资料名称，但一秒后加载页面的用户B仍然看到旧名称”则是具体的，并且可以立即理解。
获取反馈
孤立写作的效果很快会达到瓶颈。与同事分享你的写作，并请求具体的反馈。不是问它好不好，而是问他们是否能理解特定部分的解释，或者特定段落中的论点是否能说服他们。具体的问题能获得有用的反馈，模糊的问题只会得到礼貌但无益的回应。
研究你欣赏的作家
当你读到一篇异常清晰的技术文章时，停下来分析它为什么有效。结构是怎样的？作者如何引入概念？如何使用例子？如何处理过渡？批判性阅读能建立对有效写作的直觉感，这会逐渐影响你自己的写作。
不同内容类型的框架
不同的写作情境有不同的目标。以下是开发者最常见的几种技术写作类型的快速参考。
- 代码注释：目标是解释非显而易见的推理。要简洁。关注为什么，而不是做什么。
- 提交信息：目标是提供未来的上下文。使用描述性的主题，并在正文中解释动机。
- PR描述：目标是加速审查。提供上下文，解释方法，包含测试说明。
- 设计文档：目标是促进决策。在提出解决方案之前先定义问题。列出备选方案和权衡。
- ADR（架构决策记录）：目标是保留决策上下文。保持简短、事实性和可搜索性。
- 运行手册：目标是在压力下采取行动。使用编号步骤，提供验证命令，并假设读者在凌晨2点认知能力下降的情况下操作。
- 博客文章：目标是教学或提供信息。先展示价值，在细节前提供思维模型，无情地编辑。
- API文档：目标是实现集成。先展示完整的示例，然后解释参数和边缘情况。
结论
技术写作不是一种你拥有或缺乏的天赋。它是一项通过刻意练习培养的技能，就像学习编程语言或掌握框架一样。在写作上投入的开发者会成为更好的沟通者、更有效的领导者，以及对他们团队更有价值的贡献者。
从小处着手。改进你的下一次提交信息。为下一次代码审查写一个清晰的 PR 描述。为你刚写的棘手函数添加一个有意义的注释。这些微小的投资会随着时间累积，形成一种清晰的习惯，这将贯穿你的整个职业生涯。
当没有人能理解时，世界上最好的代码也会黯然失色。写作是为了让别人能够理解。