问题

文档仓库里总会累积各种"快速修复"，不知不觉间侵蚀用户体验。诸如含糊链接文本、臃肿代码示例之类的反模式会逐渐根深蒂固。这会让文档更难维护，也对开发者帮助有限。

为什么重要

反模式会催生"内容技术债 (content debt)"。它们会拉低 SEO 排名、降低可访问性，并增加读者为寻找快速解答而付出的认知负担。高质量的文档需要持续警惕，才能保持简洁、干净与专业。

方法

在 同行评审流程 中识别并坚决消除常见反模式。结合 Vale 这类自动化的正文 Lint 工具与人工评审，确保内容始终高质量、可访问且风格一致。

实现

1. 没有描述性的超链接

避免使用 “点击这里 (click here)” 或 “阅读更多 (read more)” 这类通用链接文案。这既损害 SEO，也会让依靠"跳转链接"来导航的屏幕阅读器用户无法顺利使用文档。

• ❌ 不好：要配置服务器，请 点击这里。
• ✅ 好：参阅 通用配置 来设置您的生产服务器。

2. “样板代码之墙”

代码示例中动辄几十行标准 import 与样板代码，会让读者抓不住核心逻辑。

• 解决方案：聚焦于真正相关的代码片段。若样板代码不可避免，可使用注释标出省略的部分，或使用 标注 (Callout) 解释所需的准备工作。

3. 把 FAQ 当作"垃圾堆"

“常见问题 (FAQ)” 页面常常沦为那些没能并入主指南的信息的收容所。如果一个问题的确"经常被问到"，恰恰说明您的核心文档没能把它解释清楚。

• 解决方案：与其往 FAQ 里堆内容，不如重构相关的教程或概念指南，在用户首次遇到困惑的地方就把问题解决。若信息至关重要，可使用一个 重要标注 (Important Callout)。

取舍

消除 FAQ 意味着作者要持续重构并改进既有的文档层级。短期内确实会增加维护开销，但长期来看，文档站点会显著更连贯、更专业，也更有用。