工程师撰写的文档中的常见错误以及如何修复它们

在过去的六个月中，我们的开发团队已经采用了“文档即代码”方法（您可以在本文中详细了解我们的旅程） 文章）。我定期查看技术部门同事创建的文档，编制了一份在编写技术文档时发现的最常见问题的列表。

在本文中，我将向您展示如何使用“文档即代码”方法的工具来解决这些问题。

问题 1.“文档编写不属于我们的责任”

对于整个开发团队来说，临时处理文档就像是搬起石头砸自己的脚。如果团队缺乏能力，那么就有一个令人信服的理由让文档维护更加技术驱动和可预测。

使固定：

• 将“文档即代码”方法集成到文档的开发中。这样，您就可以与代码库一起迭代更新文档，而无需承担积累技术债务的风险。
• 开发或集成一个可以呈现技术文档并作为单一信息源的空间或平台。
• 利用集成开发环境 (IDE)。 IDE 使您能够合并插件并创建用于文档开发的自定义脚本。主意是一个优秀的文档编写工具，但您可能有您最喜欢的应用程序。
• 安装拼写检查插件以防止拼写错误。将插件添加到您的 IDE 是一个快速而简单的过程。
• 采用您公司专门制定的内部指南，并考虑技术写作社区（如果有）的见解，以建立在公司内部开发文档的标准化方法。遵循这些准则将简化文档流程，节省思考准确编写内容和方式的时间。
• 根据指南自动进行检查，以显着减少或消除文档审查时间。
• 模板化一切可能的内容，并与团队就标准化文档组件达成一致。

我将提供宝贵的资源，以增强您在处理技术文档时的信心。我相信这些资源足够全面，足以帮助您有效处理技术文档：

• 这 ” Google 开发者文档风格指南》作为开发人员文档的综合手册。它涵盖了您需要了解的有关格式设置、标点符号、列表和添加代码块的所有内容。本指南足够了，并且对于制定我们的内部指南是有价值的参考，我们从中借鉴了一些内容最佳实践。
• “开发者文档对于任何参与开发人员文档工作的人来说，无论他们是开发、编写还是维护文档，都是一本必读的书。这本书收录了技术写作领域的几位知名且受人尊敬的作者。

• ”文档之类的代码技术作家 Anne Gentle 所著的《OpenStack 文档文化实用指南》。通过实际示例，作者解释了为什么文档应该在 GitHub 中进行管理，以及如何实现有效文档的技术流程。本书还提供了有价值的内容关于编写专业文档的见解，无论您是开发人员还是技术作家。

• 我还将提到编写技术文档的内部指南，其中应包括模板和格式规则。每家公司都存在这样的指导方针。通常，它们是与技术作家先锋和开发文档冠军合作开发的，并随着团队内文档文化的发展而发展。

问题 2. 单独编写文档

单独开发整个文档然后提交供审查可能会产生创建冗余或不相关文档的风险，这些文档可能与预期目的不符。

使固定：

• 始终从大纲开始，并与您的团队领导、产品负责人、技术作家或任何愿意提供专家意见的同事分享。
• 逐步编写并分配拉取请求以供上述同事审核。
• 收集并处理反馈。
• 考虑一下评论。审稿语气要放轻松，有时可能会很严厉，但这只是审稿过程的一个特点。
• 不要忽视文档流程。以下是我们公司采用的一般流程，但该流程的特点可能取决于开发团队和公司：

问题三：“需要理解的人就会理解”

我时不时地听到团队的声音：“我正在为开发团队编写”，“那些需要的人会理解”，“这就是我们团队内部历史上的演变方式”。

但专业术语和英语术语需要适当性和一致性。过度使用它们可能会导致文档类似于疯狂工程师的笔记。

对于文档，请使用尽可能简单的单词和结构。主要原则之一是为滚动而编写。编写文档可能具有挑战性，因为它通常内容广泛，但读者很少从头到尾地阅读它。相反，他们倾向于滚动或使用关键字搜索。因此，从任何部分打开文本都应该易于理解。

使固定：

• 使用词典和现行规范检查英语术语和专业术语（或者直接用谷歌搜索）。如果字典中存在某个单词，请根据您的语言拼写规则进行书写。
• 如果该语言中没有该单词，请用原始语言编写，并在括号中提供您的语言的翻译。
• 将单词添加到术语表部分，并将缩写词添加到缩写词和首字母缩写词列表中。这对于“专有”缩写尤其重要（无论关于 PO 被提及或写了多少，其含义仍然是阅读文档时常见的问题之一）。
• 一致性——在整个文档中坚持所选的写作风格和缩写（对于您公司的所有可用文档更好）。
• 仔细规划文档导航。应该有一种快速的方法来找到相关部分，而无需阅读整个文档。因此，有必要通过清晰简洁的标题来深思熟虑地构建内容。内部文档模板的开发应简单、方便。

问题 4. 在多个地方同时编写文档

对于文档来说，拥有单一事实来源——一个可以找到必要信息而不必担心其准确性的空间是至关重要的。对于我们的技术文档，内部开发的平台就是这样的空间。避免不同空间中的文档碎片对于防止过时信息误导任何人至关重要。

使固定：

• 在任何地方发布技术文档之前，如果发现公司使用多个空间进行知识共享，请确保该文档不存在于其他地方。
• 存档或删除（如果您拥有所有权）过时的技术文档。如果您担心过早删除（例如，由于页面的外部链接），请添加一个标注，说明该页面已过时，以及有效文档的当前文档位置（应在其中进行进一步更新）。
• 如果您遇到有价值的信息或见解，请将其添加到文档中。不要将其留在 Slack 或其他任何地方，尤其是在私人聊天中。知识值得分享！

安娜·冈查洛娃发表