用途:这是一个技术文档写作与整理技能,以 Diátaxis 框架作为决策工具,而非四个固定文件夹模板。它用于撰写新文档页、审计整套文档、重构混合用途文档,并帮助判断某个页面应属于哪种类型。
主要能力:按两个问题分类读者需求——需要行动还是理解、是获取技能还是应用已有技能。对应四种文档类型:教程(行动+获取)、操作指南(行动+应用)、参考(认知+应用)、解释(认知+获取)。支持创建或修订单页、审计文档集、重构混合文档,并按类型给出写作规则。
使用方式:先明确目标读者与预期结果,选一个主要文档类型,保留准确的仓库事实与示例,把明显偏离主题的内容移到更合适的页面或改为链接,并检查导航让读者有明确的下一步。进行大范围审计或信息架构调整前,建议先阅读 references/framework.md,其中记录了一手来源、指南针模型和常被忽略的区分。
适用场景:教程、操作指南、参考材料、解释性文档的撰写与分类;文档集审计,查找用户旅程缺口、误导性标题、重复内容、过期事实、死胡同和混合用途页面;混合文档重构,保留源材料并映射每个实质章节。
限制:不应用来创建空章节单纯凑齐矩阵;README 和 index.md 作为路由与导航界面,不应把其中有意为之的链接和简短描述当作重复文档;保留现有文档 frontmatter,不得借分类移除或重写仓库元数据惯例;计划、决策记录、研究笔记、发布说明和 issue 待办属于四类产品文档之外的有效文体;不要为了象限纯粹性牺牲准确性、可运行示例、可访问性或来源标注;优先渐进改进,而非无证据的全仓库重写。