SuperAPI AI 工具集

documentation-writing

写作与研究

查看项目

更新于 10-16 08:39

技能介绍

用途:按 Eight Rules 和 Diataxis 框架创建高质量、易发现的软件文档,并在触发“write documentation”“create docs”“create a README”“write a tutorial”“document this feature/module/API”“explain how this works”或任何创建 Markdown 文档的请求时自动加载。

主要能力与规则:Eight Rules 要求所有文档放在 docs/ 目录;每篇文档至少被另一篇链接;使用平实语言;示例必须可运行,而非 foo/bar 占位符;每个文件只采用一种 Diataxis 类型;标题具描述性,长文档加目录;使用相对路径链接;删除过时文档并标注更新信息。docs/ 中不得放入状态报告、进度更新、测试结果或基准、会议记录或决策、含日期的计划、时点快照;这些应分别放入 CI 日志、GitHub Issues、Pull Request 描述或提交信息。

Diataxis 文档类型与位置:Tutorial 用于学习,放 docs/tutorials/;How-To 用于完成任务,放 docs/howto/;Reference 用于查信息,放 docs/reference/;Explanation 用于理解概念,放 docs/concepts/;docs/index.md 链接全部文档。

使用方式:先判断读者的目标以确定类型,再选择对应目录;每个概念配可运行示例;在 index 中添加入口;完成前检查是否位于 docs/、是否被链接、是否无时间性信息、示例是否测试、是否只属一种类型。支持文件 reference.md 提供完整 frontmatter 规范、类型定义、Markdown 风格与评审清单;examples.md 提供各类型模板与真实示例。

应避免:无上下文的“click here”链接、不真实的 foo/bar 示例、大段文字、无索引的孤立文档、把状态写进文档。特殊情况:文档驱动开发可先写带 [PLANNED - Implementation Pending] 标记的文档,实现后移除标记并换成真实示例。官方链接与安装命令暂未提供。