为什么开发者需要掌握技术写作
浏览：1
巴克励步
我经常在客户现场看到这样的情况：研发团队一口气发布了一个很棒的功能，但产品手册却迟迟没有更新，客户遇到问题只能一遍遍找客服，或者干脆弃用。这背后其实是一个老生常谈但始终没被重视的问题：开发者不写文档，或者写出来的文档只有自己能看懂。产品手册作为用户接触产品的第一道门槛，如果写得差，再好的功能也会被埋没。Baklib 的很多客户，尤其是那些做复杂 SaaS 产品的团队，已经意识到产品手册建设不只是技术
我经常在客户现场看到这样的情况：研发团队一口气发布了一个很棒的功能，但产品手册却迟迟没有更新，客户遇到问题只能一遍遍找客服，或者干脆弃用。这背后其实是一个老生常谈但始终没被重视的问题：开发者不写文档，或者写出来的文档只有自己能看懂。产品手册作为用户接触产品的第一道门槛，如果写得差，再好的功能也会被埋没。Baklib 的很多客户，尤其是那些做复杂 SaaS 产品的团队，已经意识到产品手册建设不只是技术文档组的事，它需要开发者的深度参与。今天这篇内容，正好能帮我们理清开发者写技术文档的价值。
为了创建更好的文档
技术写作人员处于软件开发者和产品用户之间。他们需要尽可能多地了解产品或服务，以便清晰地将其传达给最终用户。但有时，开发者需要扮演技术写手的角色，创建技术文档——这就是他们应该知道如何做的原因。
你可以这样想：还有谁比制作软件的开发者更了解它呢？下面这位 Quora 用户总结得很到位：
“如果开发者是唯一的选择”来创建详细且可用的文档，那么他们掌握这项技能至关重要。
幸运的是，大多数开发者并不排斥写作任务。根据 Tom Johnson 在他技术写作博客 I'd Rather Be Writing 上的一项调查，82% 的开发者至少为自己构建的产品撰写了一部分文档。该调查还提供了另一个有趣的统计数据：Johnson 指出，十分之六的受访者认为技术写手应该转向编辑和发布高度技术性的内容（如软件文档），而不是实际编写它们。为什么？因为有些人认为，技术写手不一定有足够的知识和技能，而开发者和工程师有。但正如我们提到的，开发者应该知道如何编写技术内容，主要是为了创建更好的文档。
💛🧡🧡客户评价：作为人力资源经理，Baklib 平台非常有帮助。它允许我创建、更新和存储我们所有的公司政策、培训和其他材料集中在一个位置。我的经理可以直接访问和使用平台，减少了来找我人工传递的需要。此外，它还促进了协作，使我们更容易高效协作。
有很多资源可以学习如何做到这一点——例如，Google 的 Technical Writing Course 就是面向开发者和工程师的。当开发者学会编写技术内容后，他们就能创建出色的文档，无论是面向用户的说明手册，还是面向同行的复杂开发者文档。例如，Docker 的文档就很有帮助，提供了内部链接、速查表和章节回顾。一个非常熟练但并非开发者的技术写手也可以编写和构建这样的文档。然而，开发者本能地知道哪些信息是相关的，哪些地方需要更多解释，以及读者可能在何处遇到困难。
提高解决问题的能力
开发者每天都在解决问题。他们的工作包括运用高级技能处理设计、编码、调试等软件开发过程中的问题。在软件开发这个复杂的过程中，任何时刻都可能出错——如果问题持续存在，就意味着浪费时间、资源，最终导致用户不满。这就是为什么雇主在选择合适的开发者时，非常看重解决问题的能力。例如，根据 HackerRank 的《2018 年开发者技能报告》，解决问题的能力在所有核心能力中排名第一，甚至高于编程语言熟练度或其他技术技能。
因此，提高解决问题的能力应该是每个开发者的首要任务。但编写技术内容如何帮助提升它呢？根据 Edrolo 联合创始人、前 Google 高级助理 Duncan Anderson 的说法，写作促使开发者以一种更容易解决问题的方式进行思考。他解释说，通过写作，你可以提取想法，将问题分解为各个组成部分，并开始以不同方式思考它们。将问题分解为更易于管理的部分，是许多技术写作专家和程序员推荐的方法。例如，计算机科学家兼作家 V. Anton Spraul 认为这至关重要。幸运的是，创作技术内容是刷新该技能的好方法。以 Apple 的开发者文档为例，他们有很多部分讲解如何解决各种问题，比如诊断内存、线程和崩溃问题。他们采用将指令分解为更小步骤的方法。因此，如果开发者想要编写这样的技术文档，他们需要考虑问题以及最佳、最有效的解决方案。这不仅会巩固他们所写主题的知识，还会让解决问题逐渐成为他们的核心技能。
完善沟通技能
开发者的典型工作日是怎样的？正如你可能知道的，自己也是开发者，一个整天在办公桌前编码的形象并不代表现实。开发者通常有大量不涉及编码的日常活动，如会议、调试、代码审查等。Mac Git Survey 2021 的数据很好地说明了这一点：大多数开发者只将大约一半的工作时间花在编码上。这为其他任务腾出了时间，其中许多任务涉及沟通。与那种开发者整日埋头编码的过时形象相反，他们花大量时间与组织内外的人员沟通。一位名为 Eluda 的开发者这样解释道：“我们通常做的大部分事情都涉及与人沟通，比如你的团队、同事、客户、用户和其他开发者。”因此，既然沟通是开发者日常工作的重要组成部分，你应该尽可能提高沟通技能。而编写技术内容就是一个很好的方式。毕竟，写作是一种沟通形式。根据 Hotjar 的软件工程团队主管 Tanaka Mutakwa 的说法，编写技术内容是磨练这些技能的绝佳练习。你越磨炼写作技能，就越能向任何受众（从外行到其他开发者）呈现你的技术知识。在为非专业读者编写技术内容时，这一点尤其重要。如果你的沟通过于技术化，他们可能会对你的内容感到沮丧。简而言之，如果读者不理解你的内容，那就失去了创建内容的目的。一家似乎很理解这一点的公司是 Twilio。他们提供可编程通信工具，其文档的受众是开发者，但他们也会用清晰的英语解释概念。因此，如果你想提高沟通技能，开始写技术文档吧。
