SuperAPI AI 工具集

developer-docs-structure-audit

写作与研究

查看项目

更新于 10-16 08:45

技能介绍

用途:对已有开发者文档集做结构与可发现性审计,判断读者为何找不到所需内容。范围限于页面位置、覆盖度与可发现性;不负责撰写页面、不核对文档行为与代码是否一致、不编辑正文。若需求实为“写这一页”,应转交同类写作技能。

主要能力:逐页盘点并依据 Diátaxis 模式(教程、操作指南、参考、解释)分类,记录模式、置信度、是否混用及当前导航位置;识别错位(模式与所在分区不符)、混用(一页承担两种职责)、缺失(覆盖矩阵中产品面与模式交叉的空格);检查导航真实性,包括孤儿页、空导航项、失效内链与锚点、单页分区、层级过深、标题承诺与内容不符、同一概念多种命名、重复内容;按 CNCF TechDocs 评分标准对顶层分区打分,并计算结构记分卡;最后输出按“每小时写作与评审所修复的读者需求”排序的整改队列,并给出防漂移控制措施。

使用方式:先做访谈,问题 1-4 未答完前不得分类任何页面;随后固定证据范围、构建清单、逐页分类、找缺口、检查导航、评分、必要时做卡片分类与树测试验证、生成队列并交付报告。清单脚本示例:python3 scripts/docs-inventory.py ./docs --nav mkdocs.yml > inventory.tsv。

适用场景:已有文档集但怀疑读者找不到内容;支持工单、发布、迁移或投诉触发的审计;开源项目无专职写作者时的过渡性审计。

限制:不写页面、不验证文档与代码一致性、不改正文;无仓库或站点访问时只能基于标题,报告需注明为部分审计;结构建议在无法做用户测试时只能标为“提议”而非“已验证”;不提出空脚手架或整体重写;无法发布重定向时,移动与重命名应从队列中删除。具体阈值与评分细节以技能内参考文件为准。