当现有开发者文档结构混乱、难以导航时，用 Diátaxis…

对已存在的开发者文档集做信息架构审计：逐页盘点、按 Diátaxis 模式分类、找覆盖缺口、检查导航漂移、评分并排出优先级整改队列。

适用场景

解决思路

1. 先做访谈，一次问一个问题，能用选择题就用选择题，已回答的跳过；问题 1-4 是审计的门槛，未回答前不要分类任何页面：1) 文档在哪里（可读仓库、仅公开站点、都没有需粘贴目录树）；2) 用什么生成器（MkDocs、Docusaurus、Sphinx、VitePress、Mintlify、Starlight、Hugo、GitBook、其他或手写）；3) 读者是谁（自助采用的个人开发者、公司签约的工程团队、或两者）及生态/语言；4) 触发审计的原因（支持模式、发布、迁移、投诉或例行审查）；5) 产品真实的功能面（SDK、特性、部署目标、集成）；6) 可获取的需求信号（搜索分析、支持工单、仓库 issue、社区渠道、页面分析、销售 FAQ）；7) 站点是否已声明内容类型分类法（Diátaxis、DITA concept/task/reference、Microsoft ms.topic、Good Docs 模板、自定义或无）；8) 是否有范围外部分（自动生成 API 参考、旧版本、合作伙伴门户）；9) 能否做用户测试（卡片分类或树测试）还是仅桌面审计；10) 谁做整改、每周实际有多少写作时间、是否有可加检查的文档 CI 流水线；11) 之前是否强加过结构（Diátaxis 尝试、导航重写）及结果；12) 移动页面的约束（URL 稳定性、重定向、翻译、平台固定层级）；13) 整改必须出结果的日期；14) 想要一次性清理还是长期治理的结构。
2. 在分类前先问问题 10、12、13、14，因为它们会重排第 8 步的队列：临近日期优先拆分和移动（一天内可交付）；治理任务优先写缺失页面和漂移控制；拒绝发布重定向则从队列中彻底删除移动和重命名；仅工程师团队则把所有写作密集型动作降序。若用户无法回答问题 3，从分析中顶级入口页面推断受众，并在报告中说明受众是推断的。
3. 第 1 步——确定范围与可用证据：仓库访问可得文件树、front matter、导航配置和 git 历史；在线站点可得渲染导航和 sitemap；两者都没有则只剩标题。从评分卡中删除证据无法支持的度量，并在报告中说明。
4. 第 2 步——构建清单：先做定量清单（每页及其特征），再做定性审计，清单完整后再判断。运行清单脚本：python3 scripts/docs-inventory.py ./docs --nav mkdocs.yml > inventory.tsv。按生成器使用标志（--nav、--ext、--min-words、--format json）。从用户分析中补充脚本无法知道的列——负责人、页面浏览量、顶级搜索入口查询、顶级 404——并将每页标记为 R（冗余）、O（过时）或 T（琐碎）。不要仅凭数字分类；用数字做分诊：打开采用路径上的每一页、每页超过约 2500 词的、每页把步骤与选项表混在一起的、以及其余页面的样本。大型文档集先完整覆盖流量前 20 页再抽样。
5. 第 3 步——分类每一页：对每页主导内容应用指南针——它告知行动还是认知，服务读者技能获取（学习）还是技能应用（工作）？两个答案给出模式。若站点已声明不同分类法（问题 7），则按该分类法审计并 upfront 说明。记录每页：分配的模式、置信度、是否存在第二模式、当前在导航中的位置。两种分歧：分配模式与所在章节不符是放置问题；一页含两种模式是混合问题。仅当第二模式约占页面五分之一或包含读者必须行动的内容时才标记混合。
6. 第 4 步——找缺失内容：构建覆盖矩阵，产品功能面为行、四种模式为列、现有页面填入单元格。空格是候选缺口而非确认缺口。用需求信号确认每个候选；有证据的缺口带证据入队，无证据的缺口列为团队问题而非工作。
7. 第 5 步——检查导航是否说真话：先跑机械检查（清单脚本、导航配置、链接检查器）——孤儿页（不在导航中）、指向空处的导航项、损坏的内部链接和锚点、单页章节、超过三层的深度。报告孤儿前用 front matter 确认；draft、hidden、unlisted 是有意为之。然后手工打开页面判断：标题承诺的模式与页面实际不符（如“Getting started”实为参考堆砌、“Concepts”含步骤）；front matter 声明的内容类型与实际模式不符；同一概念在不同章节有三种叫法（如 project、workspace、org）；重复内容存在于两处且已分叉；无法承受增长的结构：扁平列表已超过约 30 项，或产品路线图将使其翻倍的类别。
8. 第 6 步——评分：评两次——CNCF TechDocs 评分对外传播，评分卡驱动整改队列。按 CNCF TechDocs 评分标准的项目文档标准，用其公布的 1-5 分制对每个顶级章节评分。然后从清单计算结构评分卡（十一项度量、计算方式及阈值来源见参考）。为每个阈值标注来源；CNCF 量表是公布的，评分卡的及格线是本技能自己的基线，评分前先与用户商定。任何 must-fix 度量失败时审计视为未完成；每批整改后重跑清单、重新评分并报告差值。
9. 第 7 步——推荐重构前先验证：分类说明今天哪里错，只有用户测试说明提议结构是否更好。当问题 9 说可测试时，用卡片分类设计类别、树测试验证，然后读结果再写队列。一个读数会直接改变计划：核心任务成功率约 80% 以上且直接路径率 60% 以上时，取消重构，把预算花在补缺口和保鲜上。无法测试时，把所有结构建议从“已验证”降级为“提议”，并更多依赖顶级 404、零结果搜索和高退出着陆页。
10. 第 8 步——把发现变成队列：按 Diátaxis 自身的小循环排序——1) 选一个；2) 评估；3) 决定产生即时改进的单一下一步；4) 做；5) 发布；6) 重复。排除两种动作：绝不提议空脚手架（不要创建空的 tutorial/howto/reference/explanation 结构）；绝不提议推倒重来（“重写文档站”不是建议）。在循环内按每小时写作和评审修复的读者需求排序，而非按关闭多少发现或最便宜。动作表：拆分混合页（一天，两半重写、两个 URL、一个重定向，无需 SME 仲裁）；合并重复（一天或更多，需有权威者决定哪份文本正确）；移动页面（一小时，路径变更加重定向）；写缺失页面（一周，之后每版刷新，永久功能面）；重命名章节（一小时编辑，但所有子 URL 和深链随之移动）。效率：拆分 > 合并 > 移动 > 写缺失页 > 重命名；价值：合并 > 写缺失页 > 拆分 > 移动 > 重命名；成本：写缺失页 > 合并 > 拆分 > 重命名 > 移动。默认先交付所有拆分，一旦重复对在采用路径上给出矛盾答案就升级到合并。缺失页会被饿死，但当同一问题在支持中反复出现或缺口在采用路径上时仍要提升它。删除而非降级被约束排除的内容：不能发布重定向的团队队列中没有移动和重命名；已通过的树测试也移除两者。说明删除了什么，把预算花在拆分和缺口上。按执行者重新排序：已有页面模板库使写缺失页更便宜；仅工程师团队使写作密集型动作昂贵；固定层级的平台使移动成本高于表格。页面必须移动且 URL 承重时，把重定向作为动作的一部分。
11. 第 9 步——交付并关闭漂移循环：按审计报告模板产出报告——结论、CNCF 章节评分、评分卡、覆盖矩阵、按严重度分组的发现、整改队列、漂移控制、审计未覆盖内容、可用输入——逐字使用该文件的发现格式和严重度层级。团队会行动时，按 CNCF 方式拆分交付物——报告、实施计划、工单。逐节呈现并取得用户同意后再继续。以漂移控制收尾：CI 验证的内容类型、页面模板、散文和链接检查、每个子树的 CODEOWNERS、每个移动 URL 的重定向、每季度重新审计。若环境有持久记忆，存储审计的持久决策：功能面列表、受众权重、商定阈值、每个争议页面分配的模式、队列状态。
12. 避免失败模式：框架崇拜（发现写成“违反 Diátaxis”，应写成读者未能获得什么）；最便宜优先队列（重命名和移动因一小时完成而置顶，应按每小时读者需求排序）；分类纠结（用“工作时/离开工作”测试，标低置信度，继续）；过度标记（200 页站点 200 条发现，只报告读者需求真正失败的页面）；范围蔓延到准确性（关于错误代码示例的发现单独标注为范围外并指定负责人）；受众盲（企业评估者内容被当作教程冗余）；静默推断（从标题分类却当作事实，按发现标注证据强度）；无治理的审计（报告交付但无 CI 检查，一年后同样混乱，漂移控制随队列一起交付而非之后）。

适用边界 · 注意事项

• 不用于撰写页面——当请求实际是“写这个页面”时，转给兄弟技能（developer-quickstart-guide、developer-tutorial、developer-troubleshooting-docs 等）。
• 不用于文档搜索排名/SEO——那用 samber/developer-relations-skills@docs-seo。
• 不用于验证文档描述的行为是否与代码一致，也不用于编辑散文。