如何长期维护文档
通过审查计划、责任模型、自动化检查和内容生命周期实践，保持文档的准确性和时效性。
文档在发布的那一刻就开始与产品脱节。功能会变化，API 会演进，UI 元素会被重命名。如果没有刻意的维护，文档会悄然成为一种负担——用户按照过时的步骤操作，遇到错误，并失去对你产品的信任。
本指南介绍如何将维护融入你的工作流程，使文档保持准确，而无需持续投入全员精力。
没有责任人的文档不会得到维护。需要有人对文档的每个部分负责，问题才能真正得到解决。
责任制并不意味着一个人写所有内容。它意味着有人对准确性负责。常见的责任模型：
- 集中式： 文档团队或技术写作人员负责所有内容。适用于较小的团队和产品，在这些情况下文档团队有足够的上下文来维护所有内容。
- 分布式： 产品、工程或团队负责人负责各自领域的文档。适用于具有专业领域的大型产品。需要一个协调人来确保一致性并发现缺口。
- 混合式： 文档团队负责核心内容（入门、导航、风格），而领域团队负责其功能的技术参考和指南。
无论你使用哪种模型，都要让责任可见——在文件本身中、在共享的电子表格中，或在你的项目管理工具中。
定期审查能在用户之前发现问题。合适的节奏取决于你的产品变化有多快。
最可靠的方法是在产品发生变化时审查文档：
- 在与代码变更相同的 pull request 中更新文档
- 在功能发布清单中包含文档检查项
- 在关闭任何改变用户可见行为的工单之前，要求文档签核
这比定期审查更可持续，因为文档更新发生在工程师或产品经理对变更记忆犹新的时候。
对于与特定功能无关的内容，定期审查可以捕捉累积的偏差：
- 每月： 审查高流量页面的准确性。这些页面影响最多的用户，因此值得更频繁地关注。
- 每季度： 审计反馈评分低或与支持工单高度相关的页面。
- 每年： 全面内容审计——查找过时的示例、已被取代的方法以及不再反映产品的内容。
手动跟踪数百个页面的审查日期无法扩展。尽可能自动化：
- 标记超过 90 天未更新的页面进行审查
- 监控搜索分析中没有返回结果的查询——这些通常表明应该存在但不存在的内容
- 使用 CI 检查在每个 pull request 中强制执行 frontmatter 要求并捕获损坏的链接
使用 automations 按计划运行自动化维护检查——标记过时内容、检查缺失的元数据，或发现反馈评分持续偏低的页面。
自动化无法取代编辑判断，但它可以减少捕获常见问题所需的手动工作。
- 损坏的链接： 在发布前运行
mint broken-links，在用户遇到之前捕获损坏的内部和外部链接。 - 风格执行： 像 Vale 这样的 linter 可以根据可配置的规则检查文本——术语一致性、被动语态、缺少标点——在每个 pull request 中执行。参阅风格与语气了解更多关于 linting 的信息。
- API 参考更新： 如果你的 API 参考是从 OpenAPI 规范生成的，请将规范生成自动化为发布流水线的一部分，这样参考文档就永远不会落后。
增量修复并不总是有效。当一个页面积累了太多的注意事项、变通方法和矛盾时，编辑它比重新开始更困难。
页面需要重写而非编辑的迹象：
- 尽管经过多轮编辑，用户仍然持续报告困惑
- 页面已经扩展到涵盖多个不同的主题，这些主题应该是单独的页面
- 产品发生了根本性变化，页面结构不再映射到功能的工作方式
- 超过一半的内容是边缘情况、注意事项或”如果……则不适用”
当你从结构化审计开始时，重写就不那么令人畏惧了：在写任何东西之前，记录缺少什么、什么具有误导性以及什么是多余的。在集中的冲刺中完成重写，而不是试图一次完成所有事情。
错误的文档比没有文档更糟糕。按照不准确步骤操作的用户会浪费时间，并失去对你的产品和团队的信心。当内容完全不准确且无法立即修复时，将其移除而不是继续保留。
移除内容时：
- 设置从旧 URL 到最相关当前页面的重定向
- 检查指向已移除页面的内部链接并更新它们
- 如果该页面被广泛使用，考虑是否在更新日志中添加简要说明