跳转到主要内容
文档在发布的那一刻就开始与产品脱节。功能会变化，API 会演进，UI 元素会被重命名。如果没有刻意的维护，文档会悄然成为一种负担——用户按照过时的步骤操作，遇到错误，并失去对你产品的信任。 本指南介绍如何将维护融入你的工作流程，使文档保持准确，而无需持续投入全员精力。

​
分配责任

没有责任人的文档不会得到维护。需要有人对文档的每个部分负责，问题才能真正得到解决。 责任制并不意味着一个人写所有内容。它意味着有人对准确性负责。常见的责任模型：
  • 集中式： 文档团队或技术写作人员负责所有内容。适用于较小的团队和产品，在这些情况下文档团队有足够的上下文来维护所有内容。
  • 分布式： 产品、工程或团队负责人负责各自领域的文档。适用于具有专业领域的大型产品。需要一个协调人来确保一致性并发现缺口。
  • 混合式： 文档团队负责核心内容（入门、导航、风格），而领域团队负责其功能的技术参考和指南。
无论你使用哪种模型，都要让责任可见——在文件本身中、在共享的电子表格中，或在你的项目管理工具中。

​
建立审查节奏

定期审查能在用户之前发现问题。合适的节奏取决于你的产品变化有多快。

​
基于触发器的审查

最可靠的方法是在产品发生变化时审查文档：
  • 在与代码变更相同的 pull request 中更新文档
  • 在功能发布清单中包含文档检查项
  • 在关闭任何改变用户可见行为的工单之前，要求文档签核
这比定期审查更可持续，因为文档更新发生在工程师或产品经理对变更记忆犹新的时候。

​
定期审查

对于与特定功能无关的内容，定期审查可以捕捉累积的偏差：
  • 每月： 审查高流量页面的准确性。这些页面影响最多的用户，因此值得更频繁地关注。
  • 每季度： 审计反馈评分低或与支持工单高度相关的页面。
  • 每年： 全面内容审计——查找过时的示例、已被取代的方法以及不再反映产品的内容。

​
使用自动化发现过时内容

手动跟踪数百个页面的审查日期无法扩展。尽可能自动化：
  • 标记超过 90 天未更新的页面进行审查
  • 监控搜索分析中没有返回结果的查询——这些通常表明应该存在但不存在的内容
  • 使用 CI 检查在每个 pull request 中强制执行 frontmatter 要求并捕获损坏的链接
使用 workflows 按计划运行自动化维护检查——标记过时内容、检查缺失的元数据，或发现反馈评分持续偏低的页面。

​
尽可能自动化

自动化无法取代编辑判断，但它可以减少捕获常见问题所需的手动工作。
  • 损坏的链接： 在发布前运行 mint broken-links，在用户遇到之前捕获损坏的内部和外部链接。
  • 风格执行： 像 Vale 这样的 linter 可以根据可配置的规则检查文本——术语一致性、被动语态、缺少标点——在每个 pull request 中执行。参阅风格与语气了解更多关于 linting 的信息。
  • API 参考更新： 如果你的 API 参考是从 OpenAPI 规范生成的，请将规范生成自动化为发布流水线的一部分，这样参考文档就永远不会落后。
  • 自动化文档草稿： 使用代理 API 在代码合并时自动生成文档草稿。

​
知道何时重写

增量修复并不总是有效。当一个页面积累了太多的注意事项、变通方法和矛盾时，编辑它比重新开始更困难。 页面需要重写而非编辑的迹象：
  • 尽管经过多轮编辑，用户仍然持续报告困惑
  • 页面已经扩展到涵盖多个不同的主题，这些主题应该是单独的页面
  • 产品发生了根本性变化，页面结构不再映射到功能的工作方式
  • 超过一半的内容是边缘情况、注意事项或”如果……则不适用”
当你从结构化审计开始时，重写就不那么令人畏惧了：在写任何东西之前，记录缺少什么、什么具有误导性以及什么是多余的。在集中的冲刺中完成重写，而不是试图一次完成所有事情。

​
移除不再适用的内容

错误的文档比没有文档更糟糕。按照不准确步骤操作的用户会浪费时间，并失去对你的产品和团队的信心。当内容完全不准确且无法立即修复时，将其移除而不是继续保留。 移除内容时：
  • 设置从旧 URL 到最相关当前页面的重定向
  • 检查指向已移除页面的内部链接并更新它们
  • 如果该页面被广泛使用，考虑是否在更新日志中添加简要说明

​
常见问题

将其设为必需步骤，而非请求。在功能的完成定义中包含文档。将文档更新放在与代码变更相同的 pull request 中——这样可以保持上下文的新鲜度，便于一起审查。当工程师意识到过时的文档会产生返回到他们那里的支持工单时，维护文档的动力就会变得更加清晰。
保持已弃用的文档可访问但明确标记。在页面顶部添加通知，说明该功能已弃用、何时将被移除以及用户应该迁移到什么。在功能实际被移除之前不要删除页面——使用旧版本的用户仍然需要它。一旦移除，将 URL 重定向到迁移指南或替代功能的文档。
两个实践涵盖了大部分价值：在与代码变更相同的 PR 中更新文档，以及在每次发布前运行 mint broken-links。这两个习惯可以防止最常见的偏差类别——过时的说明和损坏的链接——而无需专门的文档基础设施。随着团队和产品的增长，逐步添加定期审查和自动化。
按影响排序。一个每月有 5,000 次访问且满意度评分低的过时页面，比一个没人阅读的过期页面更紧急。使用分析数据按流量对内容进行排名，与反馈评分交叉参考，并与支持工单量关联，以建立一个优先级列表。修复用户实际访问的页面，而不是团队觉得杂乱的页面。