---
source: ../../../core/documentation-writing-standards.md
source_version: 1.2.0
translation_version: 1.2.0
last_synced: 2026-03-17
status: current
---

# 文件撰寫規範

> [English](../../../core/documentation-writing-standards.md) | **繁體中文**

**版本**: 1.2.0
**最後更新**: 2026-03-17
**適用範圍**: 所有軟體專案（新建、重構、遷移、維護）

---

## 目的

本標準根據專案類型定義文件需求，並提供各類文件的詳細撰寫指南。

**與其他標準的關係**:
- 補充 [documentation-structure.md](documentation-structure.md) 所定義的檔案組織
- 本標準聚焦於**內容需求**和**專案類型對照**

---

## 專案類型與文件對照

### 文件需求矩陣

| 文件 | 新建專案 | 重構 | 遷移 | 維護 | 說明 |
|----------|:-----------:|:-----------:|:---------:|:-----------:|-------------|
| **README.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 | 專案入口 |
| **ARCHITECTURE.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建議 | 系統架構 |
| **API.md** | ⚪ 如適用 | ✅ 必要 | ✅ 必要 | ⚪ 建議 | API 規格 |
| **DATABASE.md** | ⚪ 如適用 | ✅ 必要 | ✅ 必要 | ⚪ 建議 | 資料庫架構 |
| **DEPLOYMENT.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建議 | 部署指南 |
| **MIGRATION.md** | ❌ 不需要 | ✅ 必要 | ✅ 必要 | ❌ 不需要 | 遷移計畫 |
| **ADR/** | ⚪ 建議 | ✅ 必要 | ✅ 必要 | ⚪ 如適用 | 架構決策 |
| **CHANGELOG.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 | 版本歷史 |
| **CONTRIBUTING.md** | ⚪ 建議 | ⚪ 建議 | ⚪ 建議 | ⚪ 如適用 | 貢獻指南 |

**圖例**: ✅ 必要 | ⚪ 建議/如適用 | ❌ 不需要

---

### 專案類型說明

#### 🆕 新建專案

從零開始建立的軟體專案。

**必要文件**:
- README.md - 專案概述、快速開始
- ARCHITECTURE.md - 設計架構（開發前規劃）
- DEPLOYMENT.md - 部署流程
- CHANGELOG.md - 版本歷史

**建議文件**:
- API.md - 如對外提供 API
- DATABASE.md - 如使用資料庫
- ADR/ - 記錄重要技術決策

---

#### 🔄 重構專案

改善既有系統的程式碼結構、架構或技術棧，但不改變外部行為。

**必要文件**:
- README.md - 更新技術棧說明
- ARCHITECTURE.md - 新舊架構對比
- API.md - API 變更說明（如適用）
- DATABASE.md - Schema 變更說明（如適用）
- DEPLOYMENT.md - 新部署流程
- MIGRATION.md - 重構遷移計畫
- ADR/ - 記錄重構決策
- CHANGELOG.md - 詳細變更記錄

**重點**:
- MIGRATION.md 需包含回滾計畫
- ADR/ 需記錄「為何重構」及「為何選擇此方案」

---

#### 🚚 遷移專案

將系統從一個環境/平台遷移到另一個（如雲端遷移、版本升級）。

**必要文件**:
- README.md - 新環境說明
- ARCHITECTURE.md - 新架構圖
- API.md - API 相容性說明
- DATABASE.md - 資料遷移說明
- DEPLOYMENT.md - 新環境部署
- MIGRATION.md - 遷移步驟與驗證
- ADR/ - 遷移決策記錄
- CHANGELOG.md - 遷移變更記錄

**重點**:
- MIGRATION.md 是核心文件
- 需包含資料遷移驗證、回滾計畫、整合方通知

---

#### 🔧 維護專案

既有系統的日常維護、Bug 修復、小幅功能增強。

**必要文件**:
- README.md - 保持更新
- CHANGELOG.md - 記錄每次變更

**建議文件**:
- 依變更範圍更新其他文件

---

## 核心原則

> **文件是程式碼的延伸，應與程式碼同等重視。好的文件能減少溝通成本、加速新人上手、降低維護風險。**

### 文件金字塔

```
                    ┌─────────────┐
                    │   README    │  ← 入口點，快速概覽
                    ├─────────────┤
                 ┌──┴─────────────┴──┐
                 │   ARCHITECTURE    │  ← 系統總覽
                 ├───────────────────┤
              ┌──┴───────────────────┴──┐
              │  API / DATABASE / DEPLOY │  ← 技術細節
              ├─────────────────────────┤
           ┌──┴─────────────────────────┴──┐
           │    ADR / MIGRATION / CHANGELOG │  ← 變更歷史
           └───────────────────────────────┘
```

---

## 文件分類與規範

### 1. 架構文件

#### ARCHITECTURE.md

**用途**: 描述系統整體架構、模組劃分、技術選型

**必要章節**:

| 章節 | 說明 | 必要性 |
|---------|-------------|----------|
| 系統概述 | 目的、範圍、主要功能 | 必要 |
| 架構圖 | 使用 Mermaid 或 ASCII Art | 必要 |
| 模組說明 | 職責、依賴關係 | 必要 |
| 技術棧 | 框架、語言、資料庫版本 | 必要 |
| 資料流程 | 主要業務流程的資料流向 | 必要 |
| 部署架構 | 生產環境部署拓撲 | 建議 |
| 設計決策 | 關鍵決策的理由（或連結至 ADR） | 建議 |

**範本結構**:

```markdown
# 系統架構

## 1. 系統概述
[系統目的與範圍]

## 2. 架構圖
[Mermaid 或 ASCII 圖]

## 3. 模組說明
### 3.1 表現層
### 3.2 業務邏輯層
### 3.3 資料存取層

## 4. 技術棧
| 類別 | 技術 | 版本 |
|----------|------------|---------|

## 5. 資料流程
[主要業務流程圖]

## 6. 部署架構
[部署拓撲圖]
```

---

### 2. API 文件

#### API.md

**用途**: 記錄對外 API 介面

**必要章節**:

| 章節 | 說明 | 必要性 |
|---------|-------------|----------|
| API 概述 | 版本、Base URL、認證方式 | 必要 |
| 認證方式 | Token 取得、過期時間 | 必要 |
| 端點列表 | 所有 API 端點 | 必要 |
| 端點規格 | 每個端點的請求/回應格式 | 必要 |
| 錯誤碼參考 | 錯誤碼與說明 | 必要 |
| 程式碼範例 | 常見語言的範例 | 建議 |
| 速率限制 | API 呼叫頻率限制 | 如適用 |

**端點規格格式**:

```markdown
### POST /api/v1/resource

描述此端點的功能。

**請求**

| 欄位 | 類型 | 必要 | 說明 |
|-------|------|----------|-------------|
| field1 | string | 是 | 說明 |
| field2 | integer | 否 | 說明 |

**請求範例**
```json
{
  "field1": "value",
  "field2": 123
}
```

**回應**

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| success | boolean | 是否成功 |
| data | object | 回應資料 |

**回應範例**
```json
{
  "success": true,
  "data": {}
}
```

**錯誤回應**
| 代碼 | 說明 |
|------|-------------|
| 400 | 請求錯誤 |
| 401 | 未授權 |
```

---

### 3. 資料庫文件

#### DATABASE.md

**用途**: 記錄資料庫結構、關聯、索引策略

**必要章節**:

| 章節 | 說明 | 必要性 |
|---------|-------------|----------|
| 資料庫概述 | 類型、版本、連線資訊 | 必要 |
| ER 圖 | 實體關聯圖 | 必要 |
| 資料表列表 | 所有資料表及用途 | 必要 |
| 資料表規格 | 每個資料表的欄位定義 | 必要 |
| 索引說明 | 索引策略與效能考量 | 必要 |
| 遷移腳本 | 腳本位置與執行順序 | 必要 |
| 備份策略 | 備份頻率、保留期限 | 建議 |

**資料表規格格式**:

```markdown
### 資料表名稱

資料表用途說明。

**欄位定義**

| 欄位 | 資料類型 | 可空 | 預設值 | 說明 |
|--------|-----------|----------|---------|-------------|
| id | bigint | 否 | IDENTITY | 主鍵 |
| name | varchar(100) | 否 | - | 名稱欄位 |
| status | tinyint | 否 | 0 | 狀態旗標 |

**索引**

| 索引名稱 | 欄位 | 類型 | 說明 |
|------------|---------|------|-------------|
| PK_TableName | id | CLUSTERED | 主鍵 |
| IX_Status | status, created_at | NONCLUSTERED | 查詢最佳化 |

**關聯**

| 關聯資料表 | 連結欄位 | 關係 |
|---------------|--------------|--------------|
| OtherTable | id = other_id | 1:N |
```

---

### 4. 部署文件

#### DEPLOYMENT.md

**用途**: 記錄部署步驟、環境配置、故障排除

**必要章節**:

| 章節 | 說明 | 必要性 |
|---------|-------------|----------|
| 環境需求 | 硬體、軟體、網路需求 | 必要 |
| 安裝步驟 | 詳細安裝流程 | 必要 |
| 配置說明 | 配置檔參數說明 | 必要 |
| 驗證方式 | 如何確認部署成功 | 必要 |
| 故障排除 | 常見問題與解法 | 必要 |
| 監控設定 | 健康檢查、日誌位置 | 建議 |
| 擴展指南 | 如何水平/垂直擴展 | 如適用 |

**配置檔說明格式**:

```markdown
### config.yaml 設定

| 參數 | 預設值 | 說明 | 範例 |
|-----------|---------|-------------|---------|
| db.host | localhost | 資料庫主機 | `192.168.1.100` |
| db.port | 5432 | 資料庫連接埠 | - |
| app.timeout | 300 | 請求逾時（秒） | - |
```

---

### 5. 遷移文件

#### MIGRATION.md

**用途**: 記錄遷移計畫、向後相容策略、回滾程序

**必要章節**:

| 章節 | 說明 | 必要性 |
|---------|-------------|----------|
| 遷移概述 | 目標、範圍、時程 | 必要 |
| 前置準備 | 遷移前需完成的準備 | 必要 |
| 遷移步驟 | 詳細遷移流程 | 必要 |
| 驗證清單 | 遷移後驗證項目 | 必要 |
| 回滾計畫 | 失敗時的回滾步驟 | 必要 |
| 向後相容 | API/資料庫相容性說明 | 必要 |
| 整合方通知 | 需通知的外部系統 | 如適用 |

---

### 6. 架構決策記錄 (ADR)

#### docs/ADR/NNN-title.md

**用途**: 記錄重要的架構決策及其理由

**檔案命名**: `NNN-kebab-case-title.md`（例如：`001-use-postgresql.md`）

**必要章節**:

| 章節 | 說明 | 必要性 |
|---------|-------------|----------|
| 標題 | 決策名稱 | 必要 |
| 日期 | 決策日期（YYYY-MM-DD） | 必要 |
| 狀態 | proposed/accepted/deprecated/superseded | 必要 |
| 決策者 | 參與決策的人員 | 必要 |
| 背景 | 為何需要此決策 | 必要 |
| 決策 | 具體決策內容 | 必要 |
| 後果 | 決策的影響（正面/負面） | 必要 |
| 驅動因素 | 驅動決策的關鍵因素 | 建議 |
| 替代方案 | 考慮過的其他選項 | 建議 |
| 相關 ADR | supersedes/superseded-by 連結 | 如適用 |

#### ADR 生命週期

ADR 遵循定義的生命週期，具有明確的狀態轉換：

```
proposed → accepted → [deprecated | superseded]
```

| 狀態 | 意義 | 轉換 |
|------|------|------|
| **proposed** | 討論中，尚未決定 | → accepted 或撤回 |
| **accepted** | 決策生效中 | → deprecated 或 superseded |
| **deprecated** | 決策不再相關 | 終態 |
| **superseded** | 被更新的 ADR 取代 | 必須連結至後繼 ADR |

當 ADR 被取代時，加入 `superseded-by` 欄位連結到新 ADR。新 ADR 應包含 `supersedes` 欄位連結回原 ADR。

#### 何時撰寫 ADR

使用此決策矩陣（影響 × 可逆性）判斷是否需要 ADR：

| | 低影響 | 高影響 |
|---|:-----:|:------:|
| **容易逆轉** | ❌ 不需要 ADR | ⚪ 選擇性 |
| **難以逆轉** | ⚪ 選擇性 | ✅ 需要 ADR |

**「需要 ADR」的決策範例**:
- 選擇資料庫技術
- 採用新框架或語言
- 定義 API 版本策略
- 變更認證機制
- 重大架構模式變更（單體 → 微服務）

#### ADR 範本（增強版）

```markdown
# ADR-001: [決策標題]

**日期**: YYYY-MM-DD
**狀態**: proposed | accepted | deprecated | superseded
**決策者**: [參與人員列表]
**取代**: ADR-NNN（如適用）
**被取代**: ADR-NNN（如適用）

## 驅動因素

- [驅動此決策的關鍵因素 1]
- [關鍵因素 2]

## 背景

[為何需要此決策。包含技術、商業和組織脈絡。]

## 決策

[具體做出的決策。需精確且無歧義。]

## 後果

### 正面影響
- 好處 1
- 好處 2

### 負面影響
- 缺點 1
- 缺點 2

## 替代方案

### 方案 A: [名稱]
- **優點**: ...
- **缺點**: ...
- **拒絕原因**: ...

### 方案 B: [名稱]
- **優點**: ...
- **缺點**: ...
- **拒絕原因**: ...

## 參考資料

- [相關文件或外部資源]
```

---

## AI 協作文件

### 概述

現代文件必須同時為人類讀者和 AI 助手最佳化。本節提供撰寫 AI 工具能有效解析和利用的文件指南。

### Token 感知的文件設計

AI 模型有上下文視窗限制。結構化文件以提高 LLM 消費效率：

| 原則 | 說明 | 範例 |
|------|------|------|
| **前置關鍵資訊** | 將重要資訊放在前面 | 摘要先於細節 |
| **使用清晰標題** | 階層結構有助導航 | H1 > H2 > H3 |
| **保持章節原子化** | 每個章節自成一體 | 可獨立閱讀 |
| **減少冗餘** | 避免重複資訊 | 引用而非複製 |
| **使用結構化格式** | 表格和清單優於散文 | 易於解析和提取 |

**建議文件大小**:

| 文件類型 | 目標大小 | 理由 |
|---------|---------|------|
| README | 500-1000 字 | 快速概覽 |
| API 端點文件 | 每端點 200-400 字 | 聚焦且可掃描 |
| 架構文件 | 每章節 1000-2000 字 | 詳細但分塊 |
| ADR | 300-600 字 | 決策導向 |

### AI 友善的文件模式

**模式 1：結構化中繼資料區塊**

```markdown
---
title: 使用者認證 API
version: 2.1.0
last_updated: 2026-01-24
owner: auth-team
status: stable
---
```

**模式 2：清晰的章節標記**

```markdown
## Overview / 概述
## Quick Start / 快速開始
## API Reference / API 參考
## Configuration / 配置
## Troubleshooting / 故障排除
```

### LLM 最佳化寫作規則

撰寫將被 LLM 使用的文件（透過 RAG、上下文注入或直接讀取）時，遵循以下規則以最大化理解準確度：

| 規則 | 說明 | 範例 |
|------|------|------|
| **短段落** | 段落保持 3-5 行 | 將長篇說明拆成多個段落 |
| **一致術語** | 全文使用相同術語指稱相同概念 | 始終使用「使用者」而非有時「使用者」有時「客戶」 |
| **語言標籤程式碼** | 程式碼區塊總是指定語言 | ` ```javascript ` 而非 ` ``` ` |
| **避免代名詞歧義** | 跨段落時使用明確名詞取代「它」「這個」「那個」 | 「驗證服務驗證...」而非「它驗證...」 |
| **上下文自足** | 每個 H2 段落應可獨立理解 | 包含必要的上下文或交叉參考 |
| **明確否定** | 當區別重要時，明確說明某事「不是」什麼 | 「此端點建立使用者但不會發送歡迎信」 |

### 文件分塊指南

對於被檢索增強生成（RAG）系統使用的文件，結構化內容以產生有效的分塊：

- **H2 段落 ≤ 4K tokens**（約 3000 字）：每個 H2 段落應是自包含的分塊
- **每個 H2 一個主題**：避免在同一段落混合不相關的概念
- **前置摘要**：每個段落以 1-2 句摘要開始

**檢索友善的中繼資料**（選擇性 YAML frontmatter）：

```yaml
---
title: 使用者驗證 API
scope: auth-service
difficulty: intermediate
tags: [authentication, API, OAuth2, JWT]
last_validated: 2026-03-17
---
```

這些中繼資料欄位幫助檢索系統對文件進行相關性排序和篩選。

### 為 AI 程式碼生成撰寫

**包含明確限制**:

```markdown
## 驗證規則

| 欄位 | 類型 | 限制 |
|------|------|------|
| email | string | 必填，有效電子郵件格式，最多 255 字元 |
| age | integer | 必填，範圍 0-150 |
| role | string | 列舉: "admin", "user", "guest" |
```

**明確業務邏輯**:

```markdown
## 折扣計算邏輯

1. 基礎折扣 = 0%
2. 若客戶類型為 "VIP"，加 20%
3. 若訂單總額 > $100，加 5%
4. 最大總折扣 = 50%
```

---

## API 文件標準

### OpenAPI 3.1 合規性

對於 REST API，使用 OpenAPI 3.1（完全對齊 JSON Schema draft 2020-12）：

**OpenAPI 3.1 主要功能**:

| 功能 | 說明 |
|------|------|
| JSON Schema 對齊 | 與 JSON Schema 完全相容 |
| Webhooks 支援 | 一級 webhook 文件 |
| `type` 陣列 | 支援 `"type": ["string", "null"]` |

### AsyncAPI 2.6 用於事件驅動 API

對於訊息/事件驅動 API，使用 AsyncAPI 2.6：

```yaml
asyncapi: 2.6.0
info:
  title: 訂單事件
  version: 1.0.0
channels:
  orders/created:
    publish:
      message:
        $ref: '#/components/messages/OrderCreated'
```

---

## 翻譯友善寫作

對於維護多語言文件的專案，在原始文件中遵循以下寫作規則，以提升翻譯品質並減少譯者工作量。

### 寫作規則

| 規則 | 說明 | 範例 |
|------|------|------|
| **完整句子** | 避免句子片段和電報式風格 | 「服務會自動重啟。」而非「自動重啟。」 |
| **避免慣用語和俚語** | 使用國際通用的直白語言 | 「容易使用」而非「小菜一碟」 |
| **一致術語** | 建立並遵循專案術語表 | 始終使用「部署」而非有時「部署」有時「發布」 |
| **簡單句式** | 偏好 SVO（主詞-動詞-受詞）；避免巢狀子句 | 「API 回傳 JSON。」而非「當正確呼叫時 API 所回傳的 JSON...」 |
| **明確指代** | 避免跨句的歧義代名詞 | 「伺服器處理請求。」而非「它處理它。」 |

### 術語表範本

維護 `glossary.md` 檔案以確保跨翻譯的術語一致性：

```markdown
# 專案術語表

| 英文術語 | 定義 | 翻譯備註 |
|---------|------|---------|
| deployment | 將軟體發布到生產環境的過程 | 部署 |
| endpoint | API 中的特定 URL 路徑 | 端點 |
| rollback | 還原到先前版本 | 回滾 |
```

### 翻譯狀態 Frontmatter

在翻譯文件標頭追蹤翻譯狀態：

```yaml
---
translation_status: current | needs_update | in_progress
source_version: 1.2.0
source_hash: abc123
translated_by: human | machine | machine+human-review
last_synced: 2026-03-17
---
```

| 欄位 | 說明 |
|------|------|
| `translation_status` | 翻譯是否與當前原始檔案一致 |
| `source_version` | 翻譯對應的原始文件版本 |
| `source_hash` | 翻譯時原始檔案的 Git hash（精確追蹤） |
| `translated_by` | 翻譯方式，供品質評估 |
| `last_synced` | 最後同步檢查日期 |

---

## 品質標準

### 格式要求

| 項目 | 標準 |
|------|----------|
| 語言 | 繁體中文 |
| 編碼 | UTF-8 |
| 行長度 | 建議 ≤ 120 字元 |
| 圖表 | 優先使用 Mermaid，次之 ASCII Art |
| 連結 | 內部連結使用相對路徑 |

### 維護要求

| 項目 | 標準 |
|------|----------|
| 同步更新 | 程式碼變更時同步更新文件 |
| 版本標記 | 文件頂部標記版本與更新日期 |
| 審查納入 | 程式碼審查需包含文件變更 |
| 定期檢視 | 每季檢視文件是否過時 |

### 審查清單

提交文件前：

- [ ] 必要章節完整
- [ ] 無過時或錯誤資訊
- [ ] 所有連結有效
- [ ] 範例可執行/正確
- [ ] 格式符合標準

### 文件品質指標

以領先指標和滯後指標量化文件健康度。

#### 領先指標（主動）

| 指標 | 目標 | 如何衡量 | 自動化 |
|------|------|---------|--------|
| **覆蓋率** | ≥ 90% 公開 API 有文件 | 計算已文件化 vs 總端點數 | 自訂腳本或 API 規格差異比對 |
| **時效性** | 所有文件在 90 天內更新 | 檢查標頭中的 `Last Updated` 日期 | `find` + 日期比對腳本 |
| **連結健康度** | 100% 有效連結 | 檢查所有內部和外部連結 | markdown-link-check、lychee |
| **範例有效性** | 100% 程式碼範例可執行 | 擷取並執行程式碼區塊 | doctest、自訂 CI 腳本 |
| **結構合規性** | 所有文件具備必要章節 | 根據章節範本驗證 | remark-lint、自訂 linter |

#### 滯後指標（結果）

| 指標 | 說明 | 如何衡量 |
|------|------|---------|
| **支援工單減少** | 已文件化功能的問題減少 | 追蹤標記「文件」的支援工單 |
| **上手時間** | 新開發者提交首個 PR 的時間 | 衡量新人梯次平均值 |
| **文件相關 PR 評論** | 要求補文件的審查評論減少 | 計算提及「docs」的 PR 審查評論 |

#### 建議自動化工具

| 工具 | 用途 | 整合方式 |
|------|------|---------|
| **markdown-link-check** | 驗證 Markdown 檔案中的連結 | Pre-commit hook、CI |
| **lychee** | 快速連結檢查器（Rust 開發） | CI pipeline |
| **remark-lint** | Markdown 風格和結構 lint | Pre-commit hook |
| **textstat** | 可讀性評分（Flesch-Kincaid 等） | CI pipeline（建議性） |
| **vale** | 散文 lint（風格、文法、術語） | Pre-commit hook、CI |

---

## 文件位置規範

```
project-root/
├── README.md                    # 專案入口文件
├── CONTRIBUTING.md              # 貢獻指南
├── CHANGELOG.md                 # 變更日誌
├── .standards/ or .claude/      # 開發標準
│   ├── documentation-writing-standards.md
│   └── ...
└── docs/                        # 文件目錄
    ├── INDEX.md                 # 文件索引
    ├── ARCHITECTURE.md          # 架構文件
    ├── API.md                   # API 文件
    ├── DATABASE.md              # 資料庫文件
    ├── DEPLOYMENT.md            # 部署文件
    ├── MIGRATION.md             # 遷移文件
    ├── ADR/                     # 架構決策記錄
    │   ├── 001-xxx.md
    │   └── ...
    └── DB/                      # 資料庫腳本
```

---

## 工具建議

| 用途 | 工具 |
|---------|-------|
| Markdown 編輯 | VS Code + Markdown Preview Enhanced |
| 圖表繪製 | Mermaid / draw.io / PlantUML |
| API 文件 | OpenAPI (Swagger) / Redoc |
| ER 圖 | dbdiagram.io / DBeaver |

---

## 文件可及性

確保文件對所有使用者都可存取，在適用的情況下遵循 WCAG 2.1 Level A 指南。

| 需求 | 描述 | 範例 |
|------|------|------|
| **淺顯語言** | 使用清晰、簡單的語言；目標為 8 年級閱讀程度 | 避免：「utilize」→ 使用：「use」 |
| **圖片替代文字** | 為所有非裝飾性圖片提供描述性替代文字 | `![顯示三層架構的架構圖](arch.png)` |
| **標題層級** | 使用正確的標題層級（h1→h2→h3），不跳級 | 不要從 `#` 直接跳到 `###` |
| **連結文字** | 使用描述性連結文字，而非「點此」 | 避免：[點此] → 使用：[安裝指南] |
| **程式碼區塊** | 使用帶語言標示的圍欄式程式碼區塊 | ` ```javascript ` 而非 ` ``` ` |
| **色彩獨立性** | 不僅依賴色彩傳達意義 | 搭配使用 ✅/❌ 圖示與色彩 |

---

## 相關標準

- [Documentation Structure Standard](documentation-structure.md) - 文件結構標準
- [Changelog Standards](changelog-standards.md) - 變更日誌標準

---

## 參考資料

- [OpenAPI 3.1 規格](https://spec.openapis.org/oas/v3.1.0) - 最新 OpenAPI 規格
- [AsyncAPI 2.6 規格](https://www.asyncapi.com/docs/reference/specification/v2.6.0) - 事件驅動 API 文件
- [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html) - JSON Schema 規格
- [Diátaxis 文件框架](https://diataxis.fr/) - 文件結構方法論
- [Write the Docs](https://www.writethedocs.org/guide/) - 文件社群最佳實踐

---

## 版本歷史

| 版本 | 日期 | 變更內容 |
|---------|------|---------|
| 1.2.0 | 2026-03-17 | 新增：增強版 ADR 範本（生命週期、決策矩陣、取代連結）、LLM 最佳化寫作規則、文件分塊指南、翻譯友善寫作標準、文件品質指標（領先/滯後指標） |
| 1.1.0 | 2026-01-24 | 新增：AI 協作文件章節、Token 感知文件設計、API 文件標準（OpenAPI 3.1、AsyncAPI 2.6） |
| 1.0.1 | 2025-12-24 | 新增：相關標準章節 |
| 1.0.0 | 2025-12-10 | 初版文件撰寫標準 |

---

## 授權

本標準以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
