好的程序员写代码，优秀的程序员写文档。

照片由 Desola Lanre-Ologun 在 Unsplash 拍摄。

如果你让我想到一个软件工程师，你可能会想象到一个屏幕前的人，屏幕上满是五彩斑斓的代码，伴随着键盘的敲击声。代码是机器的语言，但是，但往往被忽视的是，工程师并不是为机器开发产品，我们是为人类服务的。为了更好地服务于人类，我们沟通时必须像人一样交流。

人们通常只通过他们写的代码来定义软件工程师。然而，我们工作的真正影响远不止于代码提交——这从我们如何向使用它的人解释这份工作开始。写作在工程过程中一直起着极其重要的作用，无论是技术文档、API指南、用户手册还是教程，写作都贯穿其中。

说实话——工程师通常不会把写作作为他们优先发展的技能，但它绝对是影响最大的技能之一，没有之一。原因如下：

1. 清晰促进采用：
   即使世界上最好的代码，如果没有人知道如何使用它，也是无用的。文档是产品和用户之间的接口。没有清晰的说明、教程和用户手册，产品的潜力基本上就被困惑的障碍所阻隔。
2. 撰写建立信任：
   撰写得当的文档对用户来说意味着“我尊重他们的时间和他们的体验”。这表明你不仅关心推出新功能，还关心用户能否真正使用和受益于你所建立的东西。
3. 撰写有助于协作：
   协作一直是成功的关键。清晰的写作对于技术团队成员和非技术成员之间的有效沟通至关重要。好的写作确保每个人都明白相同的要点，并且项目在共享理解和一致目标的指导下顺利推进。

写作经常被当作工程过程中的一个次要任务。它要么被匆忙地安排在最后阶段，要么干脆外包出去（我们稍后再详细讨论）。为什么我们不像对待代码那样认真对待写作呢？如果我们这样做会有什么结果？

• 像产品设计师一样思考：
  就像你为你的应用设计一个直观的界面一样，你也应该设计直观的文档资料。考虑用户如何浏览和处理信息。你的文档是否逻辑清晰易懂？它是否以引导用户逐步操作流程的方式流畅地展开？
• 迭代如开发者：
  写作不是一次性的过程。就像代码一样，它需要调试、测试和迭代。收集并跟踪用户反馈，识别差距并不断优化你的写作，直到它符合受众的需求。
• 衡量其成功：
  文档可以像产品的任何其他功能一样被评估。收集并跟踪用户反馈，观察工单中的模式，并分析参与度数据，来了解写作是否达到目的。

文档、用户指南和发布说明不仅仅是产品的附属部分，它们本身就是产品体验的一部分。它们决定了用户如何与你所构建的产品互动和感知产品。一本令人困惑的手册可能会毁掉一个原本很好的产品体验，而一个清晰的教程可以让最复杂的工具也变得易于使用。

写作不仅仅是编写文档，它是一种强有力的倡导工具。写文档的工程师们成为了他们所打造产品的首批代言人，写作也因此为我们提供了机会。

• 让技术更易于访问：把复杂概念拆解成易于理解的语言，让技术更贴近广大受众。
• 激发创新：分享你的见解、经验以及在过程中学到的教训，帮助他人在你的基础上继续创新。
• 扩大影响力：将我们工作的影响力扩大到团队之外。一篇博客或教程可以激发全球范围内的创新和变革。

在工程领域，文档工作的编写逐渐交给了被称为“技术作家”的专业人士。尽管这些“技术作家”做得不错，但工程师参与创建和改进自己的文档也很重要。如果工程师不参与这项工作，他们就失去了直接与用户沟通并解释他们工作的逻辑设计和意图的机会。

这种职责从写作过程转移到其他方面的转变可能会导致产品与其使用者之间的隔阂。工程师对所构建的产品有着独特的见解，这种见解很难被其他人复制，这使得其他人很难复制同样的成果。

当用户能够理解如何使用新功能，同事能够轻松维护它，并且其价值已经清晰地传达给所有利益相关者时，这个功能才算真正完成。

写作可能感觉相对于编码来说是一个次要任务，但实际上它是我们在传达工作时最强大的工具之一。它是我们将技术概念转化为普通人能理解的语言的方式。它确保我们的工作不仅功能强大，而且易于理解且实用。它保证我们的产品适合人们使用。

当你觉得自己完成了一个产品或只是某个功能时，不要只停留在编码阶段。写下来，写文档。像对待你的代码一样，认真对待你的文字。你正在创造的产品不仅仅是由代码组成的——它关乎人类的体验，这也从你如何传达它开始。