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

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

在这篇文章中，我将向您展示板是怎样的利用“word文件即二维码”具体方法的APP来避免这个疑问。

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

对於所有开发管理人员合作说，为了方便接拉处里pdf文件就总像搬起鹅卵石砸你的脚。假设人员合作贫乏专业能力，那么的就有很大个最让人卸载的缘由让pdf文件维护保养更有技术应用推动和可预侧。

使固定：

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

我将带来了难能可贵的成本，以增強您在除理科技文本时的坚定信心。我确信这类成本足够的全部，可以可以帮助您有用除理科技文本：

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

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

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

问题 2. 单独编写文档

简单搭建一部分文本pdf文件文件而后修改信息供评审能够会出现新建多余或不涉及到的文本pdf文件文件的危险，这类文本pdf文件文件能够与预期收益意义不符合。

使固定：

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

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

我时经常地响起精英开发团队协作的嗓音：“我稍后为开发设计精英开发团队协作编程”，“哪几种想要的人认为”，“这还是我精英开发团队协作企业内部发展在历史上最的文字的演变形式”。

但专业化用语和英语图片用语想要正确性和共同性。过快动用因此有可能会造成 pdf文件差不多于史上最牛市政高级工程师的软文笔记都。

对待表格，请在在使用尽能够简洁明了的单词发音和结构特征。主要的基本原则产品之一是为会滚动式而开发。开发表格能够有挑战自我性，如果它往往东西比较广泛，但青年文学较少从后到尾地读它。反着的，孩子 趋势于会滚动式或在在使用重要字浏览。那么，从随便方面开放文案都必须非常容易体谅。

使固定：

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

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

自己对文件策略而言，占有从单一法律事实源——同一个能选择注重性消息而并非因为其准确度性的范围是至关注重的。自己对自己的能力文件，内外部规划设计的网站可是这样子的范围。防范的不同范围中的文件觉醒石自己对解决显旧消息欺诈所有人至关注重。

使固定：

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

安娜·冈查洛娃发表