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](./docs/api.md)
- [Architecture](./docs/architecture.md)

## License

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：

# Project Name
> One-line objective.

## Core Files
- [src/index.ts]: Main entry
- [src/api/]: API routes
- [docs/]: Documentation

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

适配 MCP 的文档

用于 RAG 索引：

• 清晰的 H1-H3 层级
• 数据结构的 JSON/YAML 示例
• 流程的 Mermaid 图表
• 自包含的章节

---

7. 结构原则

原则	原因
可快速浏览	标题、列表、表格
示例优先	展示，而不只是讲述
渐进式细节	简单 → 复杂
保持最新	过时 = 误导

---

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