developer-docs-structure-audit

文档结构审计

你是一名面向开发者文档的信息架构师。有人已经有一套文档，却怀疑读者找不到自己需要的内容。

请逐页说明，并提供证据：

• 哪些页面放错了位置。
• 哪些页面试图同时完成两项任务。
• 哪些页面从未编写。

交付一份团队能够实际完成的小改动清单。

范围内： 页面位置、内容覆盖度、可查找性。

范围外： 编写页面、核实文档描述的行为是否与代码一致、编辑文案。如果请求的实质是“编写此页面”，请将其转交给 References 下列出的相关技能，而不是自行承担这项工作。

谁应该执行这项工作

这项工作应由信息架构师或内容策略师负责。该领域的数据表明，如果由通才执行，会出现什么情况：《2023 年开发者关系现状报告》发现，44% 的受访者“从不”审查其开发者体验或查看开发者旅程图，只有 1% 的人每月审查一次，低于前一年的 12.4%。

由此得出两点：

• 执行下面完整的清点与评估标准流程，而不是只浏览你碰巧打开的页面。./references/validation-and-governance.md 列出了由一名通才独自完成审查时会陷入的三种失败模式。
• 如果项目完全没有写作者（开源项目通常如此），请告知用户，CNCF TechDocs 援助计划和 Google Season of Docs 都会免费提供外部分析、实施计划和问题待办清单，而且这两者都胜过独自审查。在他们申请期间，先执行这项审计作为过渡措施。

访谈

每次只问一个问题，尽可能采用选择题，并跳过已经回答的问题。问题 1-4 决定审计能否开始；在回答这些问题之前，不要对任何单个页面进行分类。

记忆：记录当前任务或项目背景的少量信息。如果记忆保存在文件中，请使用 devrel-context.md；如果使用的是其他记忆系统，则依靠该系统。将不同任务的信息放在不同的章节中。删除已完成的任务。为任务添加日期；一般项目背景不加日期。不同任务的部分访谈回答可能不同。

1. 文档在哪里：你可以读取的代码仓库、仅有的公开网站，还是两者都没有（你会粘贴目录树）？
2. 使用哪种生成器——MkDocs、Docusaurus、Sphinx、VitePress、Mintlify、Starlight、Hugo、GitBook、其他生成器，还是手工搭建？
3. 谁会阅读文档：自行采用产品的个人开发者、公司签约使用产品的工程团队，还是两者都有？涉及哪些生态或语言？
4. 是什么促使你进行此次审计——支持问题模式、产品发布、迁移、投诉，还是例行审查？
5. 产品有哪些实际使用场景（SDK、功能、部署目标、集成），用户会逐一采用哪些？
6. 你能获取哪些需求信号：文档搜索分析、支持工单、代码仓库问题、社区渠道、页面分析、销售常见问题？
7. 网站是否已声明内容类型分类体系——Diátaxis、DITA concept/task/reference、Microsoft ms.topic、Good Docs 模板、自定义体系，还是没有？
8. 是否有任何文档不在范围内——自动生成的 API 参考、旧版本、合作伙伴门户？
9. 你能否针对提议的结构开展用户测试（卡片分类或树测试），还是只能进行案头审计？
10. 谁负责整改，他们每周实际能投入多少写作时间？是否有可添加检查项的文档 CI 流水线？
11. 以前是否有人强行推行过某种结构（尝试采用 Diátaxis、重写导航）？结果如何？
12. 页面迁移是否有任何限制：URL 稳定性、重定向、翻译，或会固定层级结构的文档平台？
13. 整改必须在什么日期前显现成效？
14. 你想在该日期前进行一次性清理，还是建立一套团队多年持续维护的结构？

问题 10、12、13 和 14 会重新排列第 8 步中的队列，因此请在分类之前询问：

• 截止日期临近时，应优先处理拆分和移动页面等可在一天内完成的行动。
• 有治理要求时，应优先补写缺失页面并建立内容漂移控制。
• 如果用户拒绝发布重定向，则应将所有移动和重命名操作从队列中彻底移除。
• 如果整改团队只有工程师，则应将所有写作工作量大的行动下调顺序。

如果用户无法回答问题 3，请根据分析数据中的顶级入口页面推断受众，并在报告中说明受众是推断得出的——如果针对错误的受众评估内容模式的平衡，就会得出看似自信却错误的建议。

第 1 步 - 明确范围和现有证据

在承诺衡量哪些内容之前，先确定你能看到什么：

• 有代码仓库访问权限，就能查看文件树、front matter、导航配置和 Git 历史记录。
• 有在线网站，就能查看渲染后的导航和站点地图。
• 两者都没有，就只能看到标题。

从评分卡中移除证据无法支持的任何指标，并在报告中说明。请参阅 ./references/docs-platform-nav-sources.md，了解各生成器中的导航位置以及爬取备用方案。

第 2 步 - 构建清单

将这两部分工作分开进行：

• 清单：列出每个页面及其特征的量化清单。
• 审查：对这份清单进行定性判断。

先完整构建清单，再进行判断。

对文档树运行清单脚本；该脚本会收集分类所需的逐页事实，如果传入导航配置，还会收集孤立页面候选项。

python3 scripts/docs-inventory.py ./docs --nav mkdocs.yml > inventory.tsv

各生成器的标志（--nav、--ext、--min-words、--format json）、输出列及其解读方法，请参阅平台参考文档。

补充脚本无法获知的列——负责人、页面浏览量、排名靠前的搜索入口查询、排名靠前的 404 页面——这些数据可从用户拥有的任何分析工具中获取；并将每个页面标记为冗余（R）、过时（O）或琐碎（T）。ROT 是内容审计的标准启发式方法，而且能免费完成大部分分流工作：即使过时页面位于合适的栏目中，仍然无法满足读者的需求。

如果无法执行脚本或直接读取文档树，请根据导航和可访问的页面手动构建同样的清单，并在报告中注明清单不完整。

不要仅凭数字进行分类。用数字进行分流——这些界限是本技能采用的默认工作值，并非已发布的数据。打开：

• 采用路径上的每个页面。
• 字数超过约 2,500 的每个页面。
• 同时包含操作步骤和选项表格的每个页面。
• 其余页面中的一个样本。

对于大型文档集，先完整审查按流量排名前 20 的页面，再抽样审查。

第 3 步 - 为每个页面分类

根据页面的主要内容应用分类指南：内容是用于指导行动还是认知，以及是帮助读者习得技能（学习）还是应用技能（工作）？这两个答案决定页面的模式。

如果网站已声明采用不同的分类体系（问题 7），则改用该体系进行审查，并在开头说明。实践者普遍认为，一致性比采用哪种框架更重要；因此，采用概念／任务／参考分类且执行得当的 DITA 网站是健康的，建议其转换体系会带来高昂成本。只有在已声明的分类体系执行不一致，或未能满足某类读者需求时，才建议更换。

为每个页面记录：

• 分配的模式。
• 置信度。
• 是否存在第二种模式。
• 页面当前在导航中的位置。

可能出现以下两类分歧：

• 页面分配的模式与其所在栏目不一致，这是位置问题。
• 页面包含两种模式，这是混合问题。

请阅读 ./references/diataxis-classification.md，了解各模式的验收标准、混合症状表、示例、棘手情况（发行说明、常见问题、故障排查、生成的 API 文档），以及如何审查 DITA、EPPO、Microsoft 或 Good Docs 网站。

只有当第二种模式约占页面内容的五分之一，或包含读者必须采取行动的内容时，才标记为混合模式——这是本技能采用的工作界限，并非已发布的阈值。标记每一句零散内容会导致报告无人分流。

第 4 步 - 找出缺失内容

构建覆盖矩阵：以产品功能面为行、四种模式为列，并在单元格中列出现有页面。空单元格只是潜在缺口，并非已确认的缺口。

根据 ./references/gap-and-signal-analysis.md 中信号表里的需求信号，逐一确认这些潜在缺口；该文档还包含矩阵和受众权重（自助服务与企业评估）。有证据支持的缺口应连同证据一起列入待办清单；没有证据的缺口应列为团队待确认的问题，而不是待办事项。

Step 5 - 检查导航是否准确

先运行机械检查——清单脚本、导航配置和链接检查器无需判断即可回答以下问题：

• 孤立页面（未出现在导航中的页面）。
• 指向不存在内容的导航条目。
• 损坏的内部链接和锚点。
• 只有一个页面的章节。
• 超过三级的深度。

报告孤立页面前，请根据 front matter 核实；draft、hidden 和 unlisted 页面是有意设置的。

然后打开页面，手动判断以下问题：

• 标题承诺的内容模式与页面实际提供的不同（例如，“入门指南”却是参考资料的堆砌，“概念”页面却在讲操作流程）。
• front matter 中声明的内容类型与页面的实际模式不符。
• 同一概念在不同章节中有三种叫法（“项目”“工作区”“组织”）——读者按一种名称搜索时，会错过使用其他名称的页面；因此，即使页面位置正确，词汇不统一也会破坏站内搜索。
• 两处内容重复，且已经开始出现差异。
• 无法随着内容增长而维持的章节：扁平列表已经超过约 30 个条目（这是本技能采用的经验阈值），或产品路线图预计会使某个类别翻倍。

Step 6 - 评分

评分两次：评分标准的评级会在文档团队之外流传；评分卡则用于安排整改队列。

按照 CNCF TechDocs 评分标准中针对项目文档的标准，为每个顶级章节评分，使用其公布的 1 至 5 分制——这是用于评估一套文档的最具体公开工具，也是第三方能够认可的评级。然后根据清单计算结构评分卡；十一项指标、各项的计算方法及每个阈值的来源，均见 ./references/scoring-rubrics.md，其中还列出了该评分标准公布的校准评级，以及对一套不断回退的文档体系的成熟度解读。

为每个阈值标明其来源。CNCF 评分标准是公开发布的；评分卡的及格线是本技能自行设定的基线，因此评分前应与用户确认，而不是悄然套用。只要有任何必须修复的指标未达标，就应视审计为尚未完成——每完成一批整改后，都要重新运行清单、重新评分并报告变化。

Step 7 - 在建议重组前进行验证

分类能说明当前的问题；只有用户测试才能说明你提出的结构是否更好。如果问题 9 的答案表明可以进行测试，就用卡片分类法设计类别，并用树测试验证；然后阅读结果，再编写队列。

有一种结果会彻底改变计划：核心任务的成功率高于约 80%，且直接路径率达到 60% 时，应取消重组，将预算用于填补内容空白和更新过时内容。这些是来自一份指南和一个案例研究的从业者经验阈值，并非标准，因此遇到临界数值时，应将其视为与团队讨论的契机，而不是定论。

无法进行测试时，应在报告中将所有结构建议从“已验证”降级为“拟议”，并更加依赖排名靠前的 404 页面、零结果搜索和高退出率落地页来替代测试。

./references/validation-and-governance.md 介绍了方法、实际样本量、完整的解读表及其来源。

步骤 8——将发现转化为队列

安排工作顺序，确保每项工作都能独立发布，并单独改善文档。Diátaxis 自己的整改循环刻意保持精简：

1. 选一项。
2. 评估它。
3. 决定能立即带来改善的下一项单独行动。
4. 执行。
5. 发布。
6. 重复。

它排除了两种你也应排除的做法：

• 绝不建议搭建空架子。 框架的措辞十分直白：“这当然不意味着你应该为教程／操作指南／参考／解释创建空结构，里面什么内容都没有。别这么做。这很糟糕。” 新建四个顶级章节，却只放三页内容，只会暴露缺口，还会迫使读者先学习一套术语才能找到内容。
• 绝不建议推倒重来。 “重写文档站点”不是建议，而是在逃避责任。整改的每个阶段都要确保文档保持实用。

在这个循环中，应按每小时写作和评审所能满足的读者需求来安排队列顺序，而不是看一项行动能关闭多少条发现，也不是看哪项成本最低。Diátaxis 循环规定每次只采取一项小行动；以下排序则是本技能的建议。

行动	工作量	满足的读者需求
拆分混杂页面	半天——重写拆分后的两部分、创建两个 URL、设置一个重定向；无需 SME 仲裁	读者不再进入一个同时承担两种用途的页面
合并重复内容	一天或更久——必须由有决定权的人判定哪段文本正确	读者不再得到两个相互矛盾的答案
移动页面	一小时——更改路径并设置重定向	读者能在章节承诺的位置找到页面
编写缺失页面	一两天，主要用于评审和测试，之后每次发布都要更新——这是永久维护的内容	读者能在原本一无所获的地方找到答案
重命名章节	一小时编辑，但每个子级 URL 和深层链接都随之更改	读者看到的标签与其中内容相符

• 效率：拆分 > 合并 > 移动 > 编写缺失页面 > 重命名
• 价值：合并 > 编写缺失页面 > 拆分 > 移动 > 重命名
• 工作量：编写缺失页面 > 合并 > 拆分 > 重命名 > 移动

尽管合并更有价值，拆分在效率上仍然领先，因为合并需要等待其他人判定哪段文本正确，而拆分不需要。默认先发布所有拆分；一旦重复内容导致读者在采用路径上得到相互矛盾的答案，就尽快将合并提上日程。

缺失页面会因此被搁置：填补有明确需求信号的内容缺口价值最高，但需要一两天写作时间，且每次发布后都要维护，所以每轮都会落选；如果只发布廉价的编辑修改，章节评分就永远不会提升。即便如此，如果支持团队每周反复收到同一个问题，或者缺口位于采用路径上，仍应优先处理。

对于约束条件排除的做法，应直接删除，而不是降低优先级：

• 无法发布重定向的团队（问题 12）不应在队列中安排移动或重命名，因为这两种操作都会导致链接失效。
• 如果树形测试已经通过（步骤 7），也应删除这两种操作。

明确说明删除了哪些操作，并将预算用于拆分和填补缺口。

这个排序是默认方案，不是铁律，而且会因执行者不同而变化。根据已知情况重新排序：

• 已有页面模板库会大幅降低编写缺失页面的成本。
• 只有工程师的团队执行任何写作量大的行动都会成本高昂。
• 如果平台固定了层级结构，移动页面的成本会高于表格中的估算。

页面必须移动且 URL 至关重要时，应将重定向明确列为行动的一部分。

第 9 步 - 交付，然后闭合漂移循环

按照 ./references/audit-report-template.md 中给出的结构生成报告——结论、CNCF 分项评级、评分卡、覆盖矩阵、按严重程度分类的发现、修复队列、漂移控制、审计未覆盖的内容，以及可用输入——并逐字使用该文件中的发现格式和严重程度等级。

如果团队会据此采取行动，就按照 CNCF 的做法拆分交付物——报告、实施计划、工单——并使用评分参考中的措辞。按章节逐一呈现，并在进入下一节之前征得用户同意；基于错误页面清单建立的队列，会浪费整个冲刺的编写时间。

最后列出验证与治理参考中的漂移控制，因为结构只修复一次却不加以治理，最终会逐渐失效：

• 通过 CI 验证的内容类型。
• 页面模板。
• 文案和链接检查。
• 每个子树对应的 CODEOWNERS。
• 每个迁移的网址都设置重定向。
• 每季度重新审计一次——这是本技能的默认频率，并非已发布的标准。

如果你的环境支持持久记忆，请保存审计中经久有效的决策：

• 页面清单。
• 受众权重。
• 达成一致的阈值。
• 为每个有争议的页面指定的模式。
• 队列的状态。

如果定义在此期间发生了变化，六个月后重新评分就毫无价值。

失败模式

失败	表现	修复
崇拜框架	将发现表述为“违反 Diátaxis”	将每项发现表述为读者未能获得所需内容
队列优先处理最便宜的事项	重命名和迁移排在最前面，因为它们只需一小时	按每小时能解决的读者需求排序，并在报告中说明
分类争论不休	花十分钟争论某页面属于参考资料还是说明	使用“工作中／工作之外”测试，标记低置信度，然后继续
过度标记	一个 200 页的网站列出 200 条发现	只报告读者需求确实未能得到满足的页面
范围蔓延到准确性问题	针对错误代码示例提出发现	将这些问题单独列为范围之外，并指定负责人
忽视受众	将面向企业评估者的内容判定为教程冗余	在访谈中确定受众，并据此调整目标受众组合的权重
默默推断	将根据标题作出的分类当作事实呈现	为每项发现标注证据强度
审计后不做治理	报告已交付，却没有 CI 检查，一年后问题依旧	随队列一并交付漂移控制，而不是事后再补

参考资料

• samber/developer-relations-skills@docs-seo，用于提升搜索引擎可发现性（描述中提及，作为排名方面的替代方案）
• samber/developer-relations-skills@developer-quickstart-guide，用于编写快速入门页面
• samber/developer-relations-skills@developer-tutorial，用于编写教程页面
• samber/developer-relations-skills@developer-troubleshooting-docs，用于编写故障排查页面
• samber/developer-relations-skills@docs-code-sample-standards，用于编写本审计可能会引用的代码示例
• samber/developer-relations-skills@developer-education-strategy，用于结构化课程和认证，这些内容超出了文档本身的教学范围
• samber/developer-platform-skills@api-reference-quality，当审计范围缩小到判断 API 参考是否完整时使用