SuperAPI AI 工具集

diataxis-organize-docs

通用与其它

查看项目

更新于 10-16 01:49

技能介绍

用途:把已有文档按 Diataxis 框架重新组织,依据读者需求把内容划分为教程、操作指南(how-to)、参考和解释四类,并建立结构化的文档层级。

主要能力:按四象限分类内容——教程面向学习、以动手方式教学;操作指南面向任务、解决具体问题;参考面向信息、描述机制与事实;解释面向理解、阐明概念与原因。支持将混合用途的文档拆分,保留上下文并跨象限建立关联。

目录结构:docs/ 下按 tutorial/、how-to/、reference/、explanation/ 组织,可再按主题增设子目录;how-to 可含 troubleshooting,reference 可含 api、configuration、architecture,explanation 可含 concepts、decisions、background。根导航文件固定使用 docs/README.md,不使用 index.md。

写作约定:生成的文档不含人工维护的总数统计和编号章节引用,使用描述性标题与命名链接;有序步骤的 Markdown 列表标记统一写为 1.,由渲染器维护编号;保留理解或使用主题所必需的数字事实。

工作流程:分析现有内容并按读者需求分类;映射到上述层级,确定保留、移动或拆分哪些文档;拆分服务多种用途的文档;构建导航并更新受移动或拆分影响的链接;最后核对完成检查。

完成检查包括:每份文档只服务一个目的;教程有明确学习成果;操作指南解决具体问题;参考完整准确;解释有实质见解;交叉引用有效且移动后仍可解析;docs/README.md 清晰表达用户意图;无孤立、重复或丢失内容。

适用场景:文档审计(报告现状、分类、建议位置与所需交叉引用)与已完成编辑(总结变更与验证)。限制:资料未提供具体安装命令、运行环境、平台支持、收费或价格信息。