> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何长期维护文档

> 通过审查计划、责任模型、自动化检查和内容生命周期实践，保持文档的准确性和时效性。

文档在发布的那一刻就开始与产品脱节。功能会变化，API 会演进，UI 元素会被重命名。如果没有刻意的维护，文档会悄然成为一种负担——用户按照过时的步骤操作，遇到错误，并失去对你产品的信任。

本指南介绍如何将维护融入你的工作流程，使文档保持准确，而无需持续投入全员精力。

<div id="assign-ownership">
  ## 分配责任
</div>

没有责任人的文档不会得到维护。需要有人对文档的每个部分负责，问题才能真正得到解决。

责任制并不意味着一个人写所有内容。它意味着有人对准确性负责。常见的责任模型：

* **集中式：** 文档团队或技术写作人员负责所有内容。适用于较小的团队和产品，在这些情况下文档团队有足够的上下文来维护所有内容。
* **分布式：** 产品、工程或团队负责人负责各自领域的文档。适用于具有专业领域的大型产品。需要一个协调人来确保一致性并发现缺口。
* **混合式：** 文档团队负责核心内容（入门、导航、风格），而领域团队负责其功能的技术参考和指南。

无论你使用哪种模型，都要让责任可见——在文件本身中、在共享的电子表格中，或在你的项目管理工具中。

<div id="build-a-review-cadence">
  ## 建立审查节奏
</div>

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

<div id="trigger-based-reviews">
  ### 基于触发器的审查
</div>

最可靠的方法是在产品发生变化时审查文档：

* 在与代码变更相同的 pull request 中更新文档
* 在功能发布清单中包含文档检查项
* 在关闭任何改变用户可见行为的工单之前，要求文档签核

这比定期审查更可持续，因为文档更新发生在工程师或产品经理对变更记忆犹新的时候。

<div id="scheduled-reviews">
  ### 定期审查
</div>

对于与特定功能无关的内容，定期审查可以捕捉累积的偏差：

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

<div id="use-automation-to-surface-stale-content">
  ### 使用自动化发现过时内容
</div>

手动跟踪数百个页面的审查日期无法扩展。尽可能自动化：

* 标记超过 90 天未更新的页面进行审查
* 监控搜索分析中没有返回结果的查询——这些通常表明应该存在但不存在的内容
* 使用 [CI 检查](/zh/deploy/ci)在每个 pull request 中强制执行 frontmatter 要求并捕获损坏的链接

<Tip>
  使用 [automations](/zh/automations) 按计划运行自动化维护检查——标记过时内容、检查缺失的元数据，或发现反馈评分持续偏低的页面。
</Tip>

<div id="automate-what-you-can">
  ## 尽可能自动化
</div>

自动化无法取代编辑判断，但它可以减少捕获常见问题所需的手动工作。

* **损坏的链接：** 在发布前运行 `mint broken-links`，在用户遇到之前捕获损坏的内部和外部链接。
* **风格执行：** 像 [Vale](https://vale.sh) 这样的 linter 可以根据可配置的规则检查文本——术语一致性、被动语态、缺少标点——在每个 pull request 中执行。参阅[风格与语气](/zh/guides/style-and-tone)了解更多关于 linting 的信息。
* **API 参考更新：** 如果你的 API 参考是从 OpenAPI 规范生成的，请将规范生成自动化为发布流水线的一部分，这样参考文档就永远不会落后。

<div id="know-when-to-rewrite">
  ## 知道何时重写
</div>

增量修复并不总是有效。当一个页面积累了太多的注意事项、变通方法和矛盾时，编辑它比重新开始更困难。

页面需要重写而非编辑的迹象：

* 尽管经过多轮编辑，用户仍然持续报告困惑
* 页面已经扩展到涵盖多个不同的主题，这些主题应该是单独的页面
* 产品发生了根本性变化，页面结构不再映射到功能的工作方式
* 超过一半的内容是边缘情况、注意事项或"如果……则不适用"

当你从结构化审计开始时，重写就不那么令人畏惧了：在写任何东西之前，记录缺少什么、什么具有误导性以及什么是多余的。在集中的冲刺中完成重写，而不是试图一次完成所有事情。

<div id="remove-what-no-longer-belongs">
  ## 移除不再适用的内容
</div>

错误的文档比没有文档更糟糕。按照不准确步骤操作的用户会浪费时间，并失去对你的产品和团队的信心。当内容完全不准确且无法立即修复时，将其移除而不是继续保留。

移除内容时：

* 设置从旧 URL 到最相关当前页面的重定向
* 检查指向已移除页面的内部链接并更新它们
* 如果该页面被广泛使用，考虑是否在更新日志中添加简要说明

<div id="frequently-asked-questions">
  ## 常见问题
</div>

<AccordionGroup>
  <Accordion title="如何让工程师在发布功能时更新文档？">
    将其设为必需步骤，而非请求。在功能的完成定义中包含文档。将文档更新放在与代码变更相同的 pull request 中——这样可以保持上下文的新鲜度，便于一起审查。当工程师意识到过时的文档会产生返回到他们那里的支持工单时，维护文档的动力就会变得更加清晰。
  </Accordion>

  <Accordion title="如何处理已弃用功能的文档？">
    保持已弃用的文档可访问但明确标记。在页面顶部添加通知，说明该功能已弃用、何时将被移除以及用户应该迁移到什么。在功能实际被移除之前不要删除页面——使用旧版本的用户仍然需要它。一旦移除，将 URL 重定向到迁移指南或替代功能的文档。
  </Accordion>

  <Accordion title="小团队的最低可行维护流程是什么？">
    两个实践涵盖了大部分价值：在与代码变更相同的 PR 中更新文档，以及在每次发布前运行 `mint broken-links`。这两个习惯可以防止最常见的偏差类别——过时的说明和损坏的链接——而无需专门的文档基础设施。随着团队和产品的增长，逐步添加定期审查和自动化。
  </Accordion>

  <Accordion title="如何对文档债务进行优先级排序？">
    按影响排序。一个每月有 5,000 次访问且满意度评分低的过时页面，比一个没人阅读的过期页面更紧急。使用分析数据按流量对内容进行排名，与反馈评分交叉参考，并与支持工单量关联，以建立一个优先级列表。修复用户实际访问的页面，而不是团队觉得杂乱的页面。
  </Accordion>
</AccordionGroup>