# Documentation Templates

> 文件範本與結構指南。README、API 文件、程式碼註解與 AI 友善文件。 Use when this capability is needed.

- Skill: `tomevault-io/documentation-templates-10` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/documentation-templates-10`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-templates-10/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/documentation-templates-10

---


# 文件範本

> 常見文件類型的範本與結構指南。

---

## 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
### 新增
- 初始發布
### 變更
- 更新依賴
### 修復
- Bug 修復
```

---

## 5. 架構決策記錄（ADR）

```markdown
# ADR-001：[標題]

## 狀態
已接受 / 已棄用 / 已取代

## 情境
為什麼我們要做這個決策？

## 決策
我們決定了什麼？

## 後果
權衡是什麼？
```

---

## 6. AI 友善文件（2025）

### llms.txt 範本

給 AI 爬蟲和代理：

```markdown
# 專案名稱
> 一行目標。

## 核心檔案
- [src/index.ts]：主要入口
- [src/api/]：API 路由
- [docs/]：文件

## 關鍵概念
- 概念 1：簡短說明
- 概念 2：簡短說明
```

### MCP 就緒文件

為 RAG 索引：
- 清晰的 H1-H3 層級
- JSON/YAML 範例用於資料結構
- Mermaid 圖表用於流程
- 自包含的章節

---

## 7. 結構原則

| 原則 | 原因 |
|------|------|
| **可掃描** | 標題、列表、表格 |
| **範例優先** | 展示，而不只是說明 |
| **漸進式細節** | 簡單 → 複雜 |
| **保持最新** | 過時 = 誤導 |

---

> **記住：** 範本是起點。根據你的專案需求調整。

---
> Source: [Tai-ch0802/skills-bundle](https://github.com/Tai-ch0802/skills-bundle) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->