文档似乎是运营中一个长期存在的问题。每个人都认同拥有文档的重要性，但很少有人相信他们的组织拥有他们所需的所有文档。有效的文档实践可以改进事件响应，加快入职速度，并有助于减少技术债务——但糟糕的文档实践可能比没有文档更糟糕。
7 宗罪
以下任何场景听起来是否熟悉？
- 你有一个 Wiki。还有一个 Google 文档存储库。还有 GitHub 文档。还有一堆你主目录中的文本文件。还有关于电子邮件中问题的注释。
- 你有一份文档解释了关于服务的方方面面，你确信你需要的信息就在那里，可以修复这个事件……在某个地方。
- 你有一个 500 行的 Puppet 清单来处理这项服务……没有注释。或者注释引用了两个票务系统之前的票据。
- 你有一堆存档的演示文稿，讨论了各种基础设施组件，但你不确定它们有多么最新，因为你已经很久没有时间观看它们了。
- 你带了一个新人加入团队，他们花了一个月的时间询问各种术语的含义。
- 你搜索你的 Wiki，找到了三份关于这项服务如何运作的独立文档，其中两份完全相互矛盾，并且过去一年中都没有更新过。
这些都是你可能犯了至少一项文档致命罪的迹象
1. 存储库过载。
2. 埋没重点。
3. 忽略注释。
4. 视频成瘾。
5. 术语过度使用。
6. 文档过度增长。
但如果你犯了其中任何一项罪，你很可能也知道这一项
7. 以上一项或多项为真，但每个人都说他们没有时间处理文档。
所有罪恶中最糟糕的是认为文档是“额外”工作。其他问题几乎总是这个错误的结果。文档不是额外的工作——它是每个项目的必要组成部分，如果不这样对待它，就几乎不可能做好。你不会期望开发人员在没有连贯的代码编写、审查和发布流程的情况下写出好的代码，然而我们经常把文档当作事后才想到的事情，我们假设它会在我们完成其他工作的同时发生。如果你认为你的文档不足，请问问自己这些问题
- 你的项目是否包括将文档制作作为可衡量的目标？
- 你是否有正式的文档审查流程？
- 文档是否被认为是团队资深成员的任务？
这种经常被忽视的态度在行业中很普遍。根据 GitHub 2017 年开源调查，大多数开源项目的第一大问题是不完整或令人困惑的文档。但是有多少项目征求技术作家来帮助改进这一点呢？我们运营部门有多少人会请技术作家来帮助编写或改进我们的文档呢？
熟能生巧（更接近）完美
这并不是说只有技术作家才能制作出好的文档，但写作和编辑像任何其他技能一样：只有当我们努力时，我们才能做得更好，但我们中很少有人这样做。我们可以采取哪些具体步骤使其成为真正的优先事项，而不是可有可无的东西？
首先，使良好的文档成为你的组织所倡导的价值。正如可靠性需要拥护者才能获得优先考虑一样，文档也需要同样的东西。项目计划和冲刺应该包括交付新文档或更新旧文档，并分配时间来这样做。确保人们理解编写好的文档与编写好的代码对他们的职业发展同样重要。
此外，使其易于保持文档更新，并让人们找到他们需要的文档。通过这种方式，你可以帮助延续文档的良性循环：高质量的文档帮助人们认识到文档的价值，并为他们自己编写文档时提供可遵循的示例，这反过来将鼓励他们创建自己的文档。
为此，尽可能少地拥有存储库；一到两个是最佳的（例如，你可能希望你的运行手册在 Google 文档中，以便在公司 Wiki 宕机时可以访问它们）。如果你有更多，请确保每个人都知道每个存储库的用途；如果 Google 文档用于运行手册，请验证所有运行手册都在那里，而不是其他任何地方，并且每个人都知道这一点。确保你的存储库可搜索并保留更改历史记录，并且为了提高可发现性，请考虑添加门户，这些门户具有常用或特别重要的文档，以便于访问。不要依赖电子邮件、聊天记录或工单作为文档的主要来源。
要求你团队中的新成员和初级成员审查你的代码和文档。如果他们不理解你的代码中发生了什么，或者你为什么做出你所做的选择，那么它可能需要重写和/或更好地注释。如果你的文档不容易理解，而无需深入研究，那么它们可能需要修改。技术文档应包括流程和行为如何工作的具体示例，以帮助人们创建心智模型。你可能会发现本文中的技巧有助于改进你的文档写作：使你的文档清晰明了的 10 个技巧。
当你编写这些文档时，尤其是在运行手册方面，请使用 倒金字塔格式：最常用的或最重要的信息应尽可能靠近页面顶部。不要将运行手册式文档和较长篇幅的技术参考结合起来；相反，链接两者并保持它们分开，以便运行手册保持精简（但可以很容易地从参考中发现，反之亦然）。
在你文档中使用这些步骤可以将其从可有可无（或更糟，负担）转变为你运营团队的倍增器。好的文档提高了包容性和知识转移，帮助你经验不足的团队成员独立解决问题，解放你更资深的团队成员去从事新项目，而不是救火或培训新人。更好的是，编写良好、高质量的文档使你和你的团队成员能够享受周末或休假，而无需在出现问题时承担责任。
在 Chastity Blackwell 的演讲 文档的 7 个致命罪 中了解更多信息，该演讲将在 LISA17 上举行，LISA17 将于 10 月 29 日至 11 月 3 日在加利福尼亚州旧金山举行。
4 条评论