mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
2138f0804d
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
125 lines
7.2 KiB
Plaintext
125 lines
7.2 KiB
Plaintext
---
|
||
title: "如何长期维护文档"
|
||
sidebarTitle: "维护"
|
||
description: "通过审查计划、责任模型、自动化检查和内容生命周期实践，保持文档的准确性和时效性。"
|
||
keywords: ["文档维护", "保持文档更新", "内容生命周期", "过时文档", "文档责任制"]
|
||
---
|
||
|
||
文档在发布的那一刻就开始与产品脱节。功能会变化，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>
|
||
使用 [workflows](/zh/agent/workflows) 按计划运行自动化维护检查——标记过时内容、检查缺失的元数据，或发现反馈评分持续偏低的页面。
|
||
</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 规范生成的，请将规范生成自动化为发布流水线的一部分，这样参考文档就永远不会落后。
|
||
- **自动化文档草稿：** 使用[代理 API](/zh/guides/automate-agent) 在代码合并时自动生成文档草稿。
|
||
|
||
<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>
|