documentation-templates

文档模板

常见文档类型的模板和结构指南。

---

1. README 结构

必备章节（按优先级排序）

章节	用途
标题 + 一句话介绍	这是什么？
快速开始	5 分钟内运行
功能	可以做什么？
配置	如何自定义
API 参考	详细文档链接
贡献	如何提供帮助
许可证	法律信息

README 模板

# Project Name

Brief one-line description.

## Quick Start

[Minimum steps to run]

## Features

- Feature 1
- Feature 2

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| PORT | Server port | 3000 |

## Documentation

- API Reference
- Architecture

## License

[Link to the actual project license; do not infer MIT]

---

2. API 文档结构

单个端点模板

## GET /users/:id

Get a user by ID.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |

**Response:**
- 200: User object
- 404: User not found

**Example:**
[Request and response example]

---

3. 代码注释指南

JSDoc/TSDoc 模板

/**
 * Brief description of what the function does.
 * 
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws ErrorType - When this error occurs
 * 
 * @example
 * const result = functionName(input);
 */

何时添加注释

✅ 添加注释	❌ 不要添加注释
原因（业务逻辑）	内容（显而易见）
复杂算法	每一行
不明显的行为	不言自明的代码
API 契约	实现细节

---

4. 更新日志模板（Keep a Changelog）

# Changelog

## [Unreleased]
### Added
- New feature

## [1.0.0] - 2025-01-01
### Added
- Initial release
### Changed
- Updated dependency
### Fixed
- Bug fix

---

5. 架构决策记录（ADR）

# ADR-001: [Title]

## Status
Accepted / Deprecated / Superseded

## Context
Why are we making this decision?

## Decision
What did we decide?

## Consequences
What are the trade-offs?

---

6. 适用于 AI 的文档（2025）

llms.txt 模板

供 AI 爬虫和 Agent 使用（示例中的 example.com 链接用于说明语法；请替换为项目实际发布的 URL）：

# Project Name
> One-line objective.

## Core Files
- [Main entry](https://example.com/project/src/index.ts): Application entry
- [API routes](https://example.com/project/src/api/): Endpoint implementation
- [Documentation](https://example.com/project/docs/): User and contributor guides

## Key Concepts
- Concept 1: Brief explanation
- Concept 2: Brief explanation

适用于 MCP 的文档

用于 RAG 索引：

• 清晰的 H1-H3 层级结构
• 使用 JSON/YAML 展示数据结构示例
• 使用 Mermaid 绘制流程图
• 内容完整独立的章节

---

7. 结构原则

原则	原因
便于浏览	标题、列表、表格
示例优先	展示，而不只是讲解
循序渐进	简单 → 复杂
保持最新	过时 = 误导

---

请记住： 模板只是起点。请根据项目需求进行调整。

适用场景

当实际项目需要 README、端点参考、更新日志、ADR 或可供 Agent 阅读的索引，并且需要根据现有惯例调整结构时使用。

局限性

• 请将示例路径、命令、日期和默认值替换为已核实的项目信息。模板不是已安装的工作流，也不能证明链接和示例有效。
• 保留实际许可证和保密范围；不要公开私有端点，也不要捏造已通过的 ADR 决策。
• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请暂停并请求澄清。