SuperAPI AI 工具集

documentation-templates

写作与研究

查看项目

更新于 10-15 18:37

技能介绍

用途

该项目提供常见文档类型的模板与结构规范,旨在帮助开发者以统一、清晰的方式编写项目文档。资料中列出了七类内容:README 结构、API 文档结构、代码注释指南、变更日志(Changelog)、架构决策记录(ADR)、AI 友好文档,以及总体结构原则。

主要能力

1. README 结构

按优先级列出必要章节:标题与一句话描述、快速开始(5 分钟内运行)、功能列表、配置方式、API 参考链接、贡献指南、许可证。并给出对应模板,包含快速开始、功能列表、配置表格(变量、描述、默认值)、文档链接和许可证。

2. API 文档结构

提供每个端点的模板,包括方法路径、功能描述、参数表格(名称、类型、是否必需、描述)、响应状态码说明,以及请求与响应示例。

3. 代码注释指南

给出 JSDoc/TSDoc 模板,说明何时应该注释(业务逻辑原因、复杂算法、非显而易见的行为、API 契约)与何时不必注释(显而易见的内容、每一行、自解释代码、实现细节)。

4. 变更日志模板

参照 Keep a Changelog 格式,分为 Unreleased 与具体版本,并用 Added、Changed、Fixed 等类别归纳。

5. 架构决策记录(ADR)

模板包含标题、状态(Accepted / Deprecated / Superseded)、背景(为何做此决策)、决策内容、后果(权衡取舍)。

6. AI 友好文档

提供 llms.txt 模板,用于 AI 爬虫和智能体,包含一句话目标、核心文件列表(入口、API 路由、文档目录)、关键概念简述。并提到面向 RAG 索引的 MCP 就绪文档要点:清晰的 H1-H3 层级、数据结构的 JSON/YAML 示例、流程的 Mermaid 图、自包含章节。

7. 结构原则

强调文档应可扫描(使用标题、列表、表格)、示例优先(展示而非仅说明)、渐进式细节(从简单到复杂)、保持最新(过时即误导)。

使用方式

资料未提供具体的安装命令、CLI 命令或代码调用方式,仅以模板文本和结构指南的形式呈现。用户可直接参照这些模板改编为项目文档。

适用场景

适用于需要编写或规范项目 README、API 文档、代码注释、变更日志、架构决策记录,以及希望让文档对 AI 工具更友好的开发团队。

限制

模板被明确定位为“起点”,需要根据项目需求进行调整。资料未提供收费、价格、平台兼容性、实际效果或详细使用步骤等信息。