documentation-templates
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDocumentation Templates
文档模板
Templates and structure guidelines for common documentation types.
各类常见文档的模板与结构指南。
1. README Structure
1. README文档结构
Essential Sections (Priority Order)
核心章节（优先级排序）
| Section | Purpose |
|---|---|
| Title + One-liner | What is this? |
| Quick Start | Running in <5 min |
| Features | What can I do? |
| Configuration | How to customize |
| API Reference | Link to detailed docs |
| Contributing | How to help |
| License | Legal |
| 章节 | 用途 |
|---|---|
| 标题 + 一句话简介 | 这是什么项目？ |
| 快速开始 | 5分钟内启动运行 |
| 功能特性 | 可以实现什么功能？ |
| 配置说明 | 如何进行自定义配置 |
| API参考 | 指向详细文档的链接 |
| 贡献指南 | 如何参与贡献 |
| 许可证 | 法律相关说明 |
README Template
README模板
markdown
undefinedmarkdown
undefinedProject Name
Project Name
Brief one-line description.
Brief one-line description.
Quick Start
Quick Start
[Minimum steps to run]
[Minimum steps to run]
Features
Features
- Feature 1
- Feature 2
- Feature 1
- Feature 2
Configuration
Configuration
| Variable | Description | Default |
|---|---|---|
| PORT | Server port | 3000 |
| Variable | Description | Default |
|---|---|---|
| PORT | Server port | 3000 |
Documentation
Documentation
- API Reference
- Architecture
- API Reference
- Architecture
License
License
MIT
---MIT
---2. API Documentation Structure
2. API文档结构
Per-Endpoint Template
单接口文档模板
markdown
undefinedmarkdown
undefinedGET /users/:id
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]
---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. Code Comment Guidelines
3. 代码注释指南
JSDoc/TSDoc Template
JSDoc/TSDoc模板
typescript
/**
* 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);
*/typescript
/**
* 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);
*/When to Comment
注释适用场景
| ✅ Comment | ❌ Don't Comment |
|---|---|
| Why (business logic) | What (obvious) |
| Complex algorithms | Every line |
| Non-obvious behavior | Self-explanatory code |
| API contracts | Implementation details |
| ✅ 需添加注释 | ❌ 无需添加注释 |
|---|---|
| 业务逻辑的原因 | 显而易见的功能 |
| 复杂算法 | 每一行代码 |
| 非直观的行为 | 自解释代码 |
| API契约 | 实现细节 |
4. Changelog Template (Keep a Changelog)
4. 更新日志模板（遵循Keep a Changelog规范）
markdown
undefinedmarkdown
undefinedChangelog
Changelog
[Unreleased]
[Unreleased]
Added
Added
- New feature
- New feature
[1.0.0] - 2025-01-01
[1.0.0] - 2025-01-01
Added
Added
- Initial release
- Initial release
Changed
Changed
- Updated dependency
- Updated dependency
Fixed
Fixed
- Bug fix
---- Bug fix
---5. Architecture Decision Record (ADR)
5. 架构决策记录（ADR）
markdown
undefinedmarkdown
undefinedADR-001: [Title]
ADR-001: [Title]
Status
Status
Accepted / Deprecated / Superseded
Accepted / Deprecated / Superseded
Context
Context
Why are we making this decision?
Why are we making this decision?
Decision
Decision
What did we decide?
What did we decide?
Consequences
Consequences
What are the trade-offs?
---What are the trade-offs?
---6. AI-Friendly Documentation (2025)
6. AI友好型文档（2025）
llms.txt Template
llms.txt模板
For AI crawlers and agents:
markdown
undefined适用于AI爬虫与Agent：
markdown
undefinedProject Name
Project Name
One-line objective.
One-line objective.
Core Files
Core Files
- [src/index.ts]: Main entry
- [src/api/]: API routes
- [src/index.ts]: Main entry
- [src/api/]: API routes
Key Concepts
Key Concepts
- Concept 1: Brief explanation
- Concept 2: Brief explanation
undefined- Concept 1: Brief explanation
- Concept 2: Brief explanation
undefinedMCP-Ready Documentation
适配MCP的文档
For RAG indexing:
- Clear H1-H3 hierarchy
- JSON/YAML examples for data structures
- Mermaid diagrams for flows
- Self-contained sections
适用于RAG索引：
- 清晰的H1-H3层级结构
- 数据结构的JSON/YAML示例
- 流程的Mermaid图表
- 独立完整的章节
7. Structure Principles
7. 结构原则
| Principle | Why |
|---|---|
| Scannable | Headers, lists, tables |
| Examples first | Show, don't just tell |
| Progressive detail | Simple → Complex |
| Up to date | Outdated = misleading |
Remember: Templates are starting points. Adapt to your project's needs.
| 原则 | 原因 |
|---|---|
| 易扫描 | 使用标题、列表、表格 |
| 示例优先 | 演示而非仅说明 |
| 渐进式细节 | 从简单到复杂 |
| 实时更新 | 过时文档会产生误导 |
注意： 模板仅作为起始参考。请根据项目需求进行调整。