SuperAPI AI 工具集

documentation-writing

写作与研究

查看项目

更新于 10-15 17:17

技能介绍

用途:该技能用于创建高质量、易发现的软件文档,遵循 Eight Rules 与 Diataxis 框架,确保文档位置正确、相互链接,并包含真实可运行的示例。

主要能力:在用户提到“写文档”“创建 README”“写教程”“解释某功能如何工作”或任何创建 Markdown 文档的请求时自动激活。核心规则包括:所有文档放在 docs/ 目录;每篇文档至少被另一篇文档链接;使用平实语言;示例必须可运行而非占位符;每个文件只对应一种 Diataxis 类型;使用描述性标题和目录;使用相对路径链接;删除过时文档并包含更新元数据。

文档类型与位置:教程(docs/tutorials/,面向学习)、操作指南(docs/howto/,面向任务)、参考(docs/reference/,面向信息)、解释(docs/concepts/,面向理解)。工作流为:确定文档类型、选择位置、编写带可运行示例的内容、从索引链接、按清单验证。

限制:docs/ 中不应包含状态报告、测试结果、会议记录、带日期的计划或时间点快照;这些应放在 CI 日志、GitHub Issues、PR 描述或提交信息中。若在实现前编写文档,需使用 [PLANNED] 标记,实现后移除并替换为真实示例。完整规范与模板见 reference.md 和 examples.md。