问题

随着时间的推移，文档存储库往往会积累一些针对内容问题的“快速修复”，这些修复会无意中侵蚀用户体验。这些反模式——例如模糊的链接文本或臃肿的代码示例——在项目中根深蒂固，使得文档难以维护，对开发者的价值也随之降低。

为什么重要

反模式会导致“内容债务”。它们会降低搜索引擎排名 (SEO)，降低残障人士的可访问性，并显著增加读者的认知负荷，而读者仅仅是想快速找到技术问题的解决方案。高质量的文档需要不断的警惕，以保持其整洁、简练且专业。

方法

在 同行评审流程 中识别并无情地消除常见的反模式。使用 Vale 等自动化的散文检查工具以及人工审核，确保您的内容在所有页面上保持高质量、易于访问且一致。

实施

1. 非描述性超链接

避免在链接中使用“点击这里”或“阅读更多”等通用文本。这不仅对 SEO 有害，还会导致使用屏幕阅读器的用户无法访问文档，因为他们通常通过在链接之间跳转来浏览页面。

• ❌ 错误示例：要配置您的服务器，请 点击这里。
• ✅ 正确示例：查看 全局配置 以设置您的生产服务器。

2. “样板代码墙”

在代码示例中，如果核心逻辑之前包含数十行标准导入和样板配置，会分散读者对示例实际重点的注意力。

• 解决方案：专注于相关的代码片段。如果为了提供上下文而必须包含样板代码，请使用注释说明为了简洁而省略了标准导入，或者使用 标注 来解释所需的设置。

3. 将 FAQ 视为“垃圾场”

“常见问题解答”(FAQ) 页面往往成为了难以整合进主指南的信息库。如果一个问题确实是“经常被问到”的，这清楚地表明您的核心文档未能有效地解释该概念。

• 解决方案：不要将其添加到 FAQ，而是重构相关的教程或概念指南，在用户首次遇到困惑的地方直接解决它。如果信息对操作成功至关重要，请使用 重要标注。

权衡

消除 FAQ 要求作者在发现新的支持问题时不断重构和改进现有的文档层级。虽然这比简单地在 FAQ 列表末尾添加一个要点增加了更多的初始维护开销，但它会为您的用户带来一个更加连贯、专业且实用的文档网站。