mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
bbb1a08ed3
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
46 lines
2.4 KiB
Plaintext
46 lines
2.4 KiB
Plaintext
---
|
||
title: "维护"
|
||
description: "让你的文档长期保持准确并持续更新。"
|
||
keywords: ["maintenance", "content lifecycle", "stale content"]
|
||
---
|
||
|
||
<Tip>
|
||
本页介绍从自动化检查到内容生命周期的一系列策略，帮助你让文档长期保持准确且有价值。
|
||
</Tip>
|
||
|
||
<div id="automate-what-you-can">
|
||
## 尽可能实现自动化
|
||
</div>
|
||
|
||
在可行的地方引入自动化，例如：
|
||
|
||
* **跟踪过时内容：** 运行脚本标记过去三个月未更新的重要文档。它们是否仍然准确？
|
||
* **自动更新文档：** 构建工作流，当代码合并时，通过 [agent API](/zh/guides/automate-agent) 自动更新文档。
|
||
* **用 linter 强制执行标准：** 使用 [Vale](http://Vale.sh) 或 [CI 检查](/zh/deploy/ci)，在每个拉取请求（PR；亦称“合并请求”/Merge Request）中自动捕获格式问题、写作风格偏差或缺失的 metadata。
|
||
|
||
<div id="set-up-a-review-process">
|
||
## 建立评审流程
|
||
</div>
|
||
|
||
文档不必追求完美——这没关系。你应设定一个可接受的标准，只要文档可用且有用即可。
|
||
|
||
在效率与质量之间取得平衡：
|
||
|
||
* **聚焦高影响力文档。** 并非每个页面都需要定期更新。务必定期审查最重要的页面，确保其准确且具备时效性。
|
||
* **善用社区力量。** 如果你的文档是开源的，赋予用户通过拉取请求（PR；亦称“合并请求”/Merge Request）标记问题或提交修复的能力。这有助于建立信任并保持内容新鲜。
|
||
|
||
<div id="know-when-to-rewrite">
|
||
## 何时该重写
|
||
</div>
|
||
|
||
随着时间推移，文档难免会累积各类注意事项和权宜之计。当渐进式修补带来的困惑多于清晰时，全面重构可能是更优选择。
|
||
|
||
* **规划定期归零。** 一次大规模清理，尤其是在最佳实践或产品本身已有显著演进时，能为团队和用户节省时间。
|
||
* **从结构化盘点开始。** 在重写前，访谈支持团队、分析用户反馈，并记录缺失、误导或冗余的内容。
|
||
* **以聚焦冲刺完成重写。** 全面重构不必一蹴而就，优先处理影响最大的部分。
|
||
|
||
<div id="wrong-docs-can-be-worse-than-no-docs">
|
||
## 错误的文档可能比没有文档更糟
|
||
</div>
|
||
|
||
过时或带有误导性的文档会浪费用户时间并侵蚀信任。如果某个页面完全不准确且短期内无法修复，通常最好直接移除。与错误的信息相比，用户更希望看到更少但正确的信息。 |