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