documentation-templates

# 文档模板 > 常见文档类型的模板和结构指南。 --- ## 1. README 结构 ### 核心部分（优先级排序） | 部分 | 目的 | |---------|---------| | **标题 + 一句话简介** | 这是什么？ | | **快速开始** | 5 分钟内运行 | | **功能特性** | 我能做什么？ | | **配置** | 如何自定义 | | **API 参考** | 详细文档链接 | | **贡献指南** | 如何提供帮助 | | **许可证** | 法律声明 | ### README 模板 markdown # 项目名称 简短的一句话描述。 ## 快速开始 [运行的最小步骤] ## 功能特性 - 功能 1 - 功能 2 ## 配置 | 变量 | 描述 | 默认值 | |----------|-------------|---------| | PORT | 服务器端口 | 3000 | ## 文档 - [API 参考](./docs/api.md) - [架构](./docs/architecture.md) ## 许可证 MIT --- ## 2. API 文档结构 ### 单个端点模板 markdown ## GET /users/:id 通过 ID 获取用户。 **参数：** | 名称 | 类型 | 必填 | 描述 | |------|------|----------|-------------| | id | string | 是 | 用户 ID | **响应：** - 200: 用户对象 - 404: 用户未找到 **示例：** [请求和响应示例] --- ## 3. 代码注释指南 ### JSDoc/TSDoc 模板 typescript /** * 函数功能的简要描述。 * * @param paramName - 参数描述 * @returns 返回值描述 * @throws ErrorType - 抛出此错误的情况 * * @example * const result = functionName(input); */ ### 何时添加注释 | ✅ 应该注释 | ❌ 不必注释 | |-----------|-----------------| | 为什么（业务逻辑） | 是什么（显而易见） | | 复杂算法 | 每一行代码 | | 非直观行为 | 自解释代码 | | API 契约 | 实现细节 | --- ## 4. 更新日志模板 (Keep a Changelog) markdown # 更新日志 ## [未发布] ### 新增 - 新功能 ## [1.0.0] - 2025-01-01 ### 新增 - 初始版本 ### 变更 - 更新依赖 ### 修复 - 错误修复 --- ## 5. 架构决策记录 (ADR) markdown # ADR-001: [标题] ## 状态 已接受 / 已弃用 / 已取代 ## 背景 为什么我们要做出这个决定？ ## 决策 我们决定了什么？ ## 后果 权衡是什么？ --- ## 6. AI 友好型文档 (2025) ### llms.txt 模板 针对 AI 爬虫和智能体： markdown # 项目名称 > 一句话目标。 ## 核心文件 - [src/index.ts]: 主入口 - [src/api/]: API 路由 - [do