SuperAPI AI 工具集

diataxis

写作与研究

查看项目

更新于 10-15 17:30

技能介绍

Diátaxis 是一套系统化的文档框架,用于按用途对文档进行分类与写作。它用两个维度划分出四种文档类型:面向学习(获取知识)与面向工作(应用知识),以及行动(做)与认知(想)。四类分别为:教程(Tutorials,学习导向,带读者动手实践、尽早给出可见结果、尽量少解释并改为链接)、操作指南(How-to guides,目标导向,面向已具备能力的用户解决具体现实目标,用条件式祈使句、假定用户已胜任)、参考(Reference,信息导向,对机制做技术性描述,保持中立、结构镜像产品、只配示例不展开解释)、解释(Explanation,理解导向,用讨论式写法建立联系与背景,回答“能否讲讲……”)。

使用方式:先分类内容,可用“行动还是认知”“学习还是工作”两个问题定位类型;再检查是否类型混杂,把教程里的解释、参考里的指导拆出去;应用对应类型的原则;不同类型之间用链接交叉引用,而不是嵌在一起。框架强调不要先建空的四段结构再填充,应让结构从内容中自然产生。仓库提供按需加载的参考文件,例如 references/tutorials.md、references/how-to-guides.md、references/reference.md、references/explanation.md、references/compass.md、references/tutorials-how-to.md、references/reference-explanation.md、references/how-to-use-diataxis.md、references/foundations.md、references/map.md、references/quality.md、references/complex-hierarchies.md。

适用场景包括编写教程、README、入门指南、操作指南与 API 参考等文档。限制:不要混用类型;内容尚不充分时不应强行套用四类结构。资料未提供收费、平台或其他实现细节。