documentation-templates

Documentation Templates - 技术文档模板与结构规范

技能概述

提供各类技术文档的标准模板和结构指南，帮助开发者快速编写 README、API 文档、代码注释和 AI 友好文档。

适用场景

1. 开源项目启动

新建项目时，直接使用现成的 README 模板，快速搭建项目文档框架，确保包含快速开始、功能特性、配置说明、贡献指南等必备章节。

2. API 接口文档编写

为 REST API 生成标准的接口文档结构，统一描述请求参数、响应格式、状态码和示例，让接口文档清晰易读。

3. AI 索引友好文档

按照 llms.txt 和 MCP-Ready 规范编写文档，使 AI 爬虫和 RAG 系统能够正确理解和索引项目内容。

核心功能

README 结构模板

提供业界验证的 README 标准结构，包含标题、快速开始、功能列表、配置说明、文档链接等核心章节，并给出完整的 Markdown 模板代码。

API 文档规范

为每个 API 端点提供统一的文档模板，标准化参数表格、响应说明和示例代码，确保 API 文档的一致性和可读性。

代码注释指南

提供 JSDoc/TSDoc 标准注释模板，明确何时需要注释、何时不需要注释，帮助团队建立一致的代码注释规范。

多场景文档模板

覆盖 Changelog（变更日志）、ADR（架构决策记录）、llms.txt（AI 友好文档）等多种文档场景，每种模板都包含结构说明和示例代码。

常见问题

README 必须包含哪些内容？

核心内容包括项目标题、一句话简介、快速开始、功能列表、配置说明、文档链接和开源协议。快速开始尤其重要，应让用户在 5 分钟内能够运行项目。

代码注释应该写什么？

注释应该解释"为什么"（业务逻辑原因），而不是"是什么"（代码本身）。需要注释的场景包括复杂算法、非显而易见的行为、API 契约等，不要注释每一行代码或自解释的简单逻辑。

如何让文档对 AI 更友好？

使用清晰的 H1-H3 标题层级、提供完整的 JSON/YAML 示例、使用 Mermaid 图表展示流程、保持章节独立完整。可以创建 llms.txt 文件，列出核心文件路径和关键概念说明。