tai-ch0802/documentation-templates

文件範本

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

---

1. README 結構

必要章節（優先順序）

| 章節 | 用途 | |------|------| | 標題 + 一行描述 | 這是什麼？ | | 快速入門 | 5 分鐘內運行 | | 功能 | 我能做什麼？ | | 設定 | 如何自訂 | | API 參考 | 連結到詳細文件 | | 貢獻 | 如何幫忙 | | 授權 | 法律 |

README 範本

# 專案名稱

簡短一行描述。

## 快速入門

[運行的最少步驟]

## 功能

- 功能 1
- 功能 2

## 設定

| 變數 | 描述 | 預設值 |
|------|------|--------|
| PORT | 伺服器埠口 | 3000 |

## 文件

- [API 參考](./docs/api.md)
- [架構](./docs/architecture.md)

## 授權

MIT

---

2. API 文件結構

每個端點的範本

## GET /users/:id

透過 ID 取得使用者。

**參數：**
| 名稱 | 型別 | 必填 | 描述 |
|------|------|------|------|
| id | string | 是 | 使用者 ID |

**回應：**
- 200：使用者物件
- 404：找不到使用者

**範例：**
[請求和回應範例]

---

3. 程式碼註解指南

JSDoc/TSDoc 範本

/**
 * 函式功能的簡短描述。
 *
 * @param paramName - 參數描述
 * @returns 回傳值描述
 * @throws ErrorType - 此錯誤發生的時機
 *
 * @example
 * const result = functionName(input);
 */

何時加註解

| ✅ 要註解 | ❌ 不要註解 | |-----------|-------------| | 為什麼（業務邏輯）| 什麼（顯而易見的）| | 複雜演算法 | 每一行 | | 非顯而易見的行為 | 自解釋的程式碼 | | API 契約 | 實作細節 |

---

4. 變更日誌範本（Keep a Changelog）

# 變更日誌

## [未發布]
### 新增
- 新功能

## [1.0.0] - 2025-01-01
### 新增
- 初始發布
### 變更
- 更新依賴
### 修復
- Bug 修復

---

5. 架構決策記錄（ADR）

# ADR-001：[標題]

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

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

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

## 後果
權衡是什麼？

---

6. AI 友善文件（2025）

llms.txt 範本

給 AI 爬蟲和代理：

# 專案名稱
> 一行目標。

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

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

MCP 就緒文件

為 RAG 索引：

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

---

7. 結構原則

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

---

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