如何建立文档文化

你们当中有些人可能不喜欢写文档，大多数人甚至可能很讨厌写文档。写文档常常被视为一项烦人但又不得不做的任务，总是被拖到最后一刻，有时甚至完全被遗忘。然而，写文档之所以重要，原因有很多：

• 文档编写不完善会造成技术债务。

• 如果文档质量差，你的同事（尤其是新团队成员）或最终用户就不得不向你提问——这会浪费你的时间！

• 如果没有文档，就会形成知识孤岛，只有少数工程师了解你技术中的某个方面是如何运作的。如果这些人离开团队，就会造成知识断层。

如果您认为贵公司缺乏文档，无论是科技创业公司还是成熟的软件公司，您都可以采取一些措施来尝试建立更好的文档文化。

1. 找个人来开它

如果你的团队中还没有技术撰稿人、用户体验撰稿人或内容专家，而且预算充足，那就聘请一位吧！他们将成为你建立文档文化的基础。

或者，您可以尝试寻找一位“文档编写者”——或者“文档之友”——一位程序员，或者是一位优秀的测试人员，他/她文笔好，对您现有的文档有足够的了解，并且愿意帮助推动文档编写工作。

2. 创建风格指南

你可以通过选择或编写风格指南来建立一种质量控制机制。风格指南将成为你确保最佳实践的参考依据，涵盖术语、大小写、语法、语气和语调等方面。如果你没有时间或资源编写自己的风格指南，可以采用现有的风格指南。大多数技术写作者都会参考以下风格指南之一：

• 微软写作风格指南（原微软风格手册）
• 芝加哥格式手册
• Google开发者文档风格指南。

您还可以在Write the Docs上找到一些有用的样式资源，这是一个由关心文档的人们组成的全球社区。那里甚至有一个专门介绍样式指南的页面！

3. 使用拼写检查器和语法检查器

另一种确保技术内容一致性的方法是鼓励使用拼写检查器和代码检查工具。如果您使用 Atom 或 Sublime 等开源文本编辑器，可以安装免费的拼写检查工具，以提高拼写和语法的准确性和一致性。您可以考虑使用以下一些代码检查工具：

• Alex：Linter 可在多个平台上使用。
• 美式拼写检查器：用于将拼写恢复为美式拼写的工具。如果您来自欧洲、亚洲或非洲，但为一家使用美式拼写的美国公司工作，这将非常有用。
• Hemingway：一款检查内容中是否存在被动语态并给出可读性等级的应用程序（等级越高，意味着您的文本可能令读者感到困惑或乏味）。
• Write Good：面向开发者的英文散文代码检查工具。适用于 Atom 和 Visual Studio。
• Vale：一款自然语言代码检查工具，支持纯文本、标记语言和源代码注释。可通过命令行界面 (CLI) 和桌面应用程序使用。

或者，您可以创建某种形式的提交前检查或筛选器，​​以防止特定的拼写错误或笔误。虽然这可能有点过于严苛，但我已经创建了几个提交前检查，以防止我当前团队的开发人员使用含义模糊的术语。

4. 提出错误

提高文档意识的另一个好方法是，针对产品本身或代码库中的拼写或语法问题提出错误报告。

当我加入一家创业公司时，我最初很担心提出 bug 会影响开发人员的开发速度，但在几个月的时间里，我指出了拼写错误、被动语态和错别字等问题，越来越多的工程师开始向我咨询有关错误消息、发布说明、参数名称和代码注释等内容的问题，因此我们能够确保文本从一开始就是正确的。

5. 奖励写作

虽然听起来可能有点不近人情，但为同事提供奖励或激励措施来鼓励他们参与文档编写，或许可行。您可以考虑以下几种方式：

• 举办“文档马拉松”或一日文档冲刺活动，并为贡献最多文档更改的人提供奖品。
• 如果你的公司有类似Bonusly 的同侪奖励计划，可以给贡献者积分作为文档工作的奖励。
• 对文档撰写做出贡献的人提供实物奖励或纪念品，例如贴纸或马克杯。

作为一名懵懂的初级技术文档编写员，我甚至成功地给帮助我编写文档的开发人员买了巧克力棒作为礼物，但我不确定这对于你的同事或你的钱包来说是否是最健康的选择！

6. 提供文件编制培训

如果你是大型开发团队中唯一的文档编写者，指望你一个人写完所有文档是不现实的。最好的办法是教你的团队一些文档编写的最佳实践，以提高文档质量。你可以涵盖以下一些主题：

• 语态：使用主动语态而非被动语态。被动语态可能会造成歧义。
• 歧义：避免使用可能造成歧义的词语。例如，如果某项行为是强制性的，请使用“你必须做x”而不是“你应该做x”。“应该”一词暗示该行为是可选的。
• 受众：鼓励你的团队思考他们的写作对象是谁，以及他们可能需要的任何先决知识或工具。

7. 做关于文档编写的演讲

我以前非常害怕公开演讲，但在过去的两年里，我做了许多关于文档编写和最佳实践的内部和外部演讲。

这不仅是检验自我、克服恐惧（如果你不擅长公开演讲）的好方法，而且还有助于提高公司和更广泛的社区对技术文档重要性的认识。

8. 利用开源社区

如果你的产品是开源的，你可以联系开源社区的技术撰稿人和文档编写人员来帮助你编写文档。

有些公司，例如谷歌，会开展开源项目，并付费聘请技术撰稿人参与开源项目。更多详情请参见“文档季” 。

概括

总而言之，如果您想着手建立某种形式的文档文化并改进公司的技术内容：

• 找一位作家或“纪录片导演”来执导这些纪录片。
• 创建或选择风格指南以建立一致性。
• 使用拼写检查器或代码检查工具来确保质量。
• 提交错误报告以提高文档意识。
• 奖励写作以鼓励他人投稿。
• 提供培训以增强同事的能力。
• 举办讲座，启发和教导他人有关文档的知识。
• 如果需要更多帮助，请使用开源软件！

可能还有很多其他方法可以尝试，但如果你尝试一下这些建议，我相信你就能朝着在公司建立文档文化迈进一大步。祝你好运！