---
source: ../../../core/documentation-lifecycle.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-03-27
status: current
---

# 文件生命週期標準

> **語言**: [English](../../../core/documentation-lifecycle.md) | 繁體中文

**版本**: 1.0.0
**最後更新**: 2026-03-27
**適用範圍**: 所有具有文件的軟體專案
**範圍**: universal
**業界標準**: ISO/IEC 26514（系統與軟體工程 — 使用者資訊的設計與開發）、ISO/IEC 26515（敏捷文件）、Docs as Code
**參考**: [documentation-structure.md](../../../core/documentation-structure.md), [documentation-writing-standards.md](../../../core/documentation-writing-standards.md)

---

## 目的

本標準定義文件的**何時更新**、**何時檢查**、以及**誰負責**。它與現有文件標準互補：

| 標準 | 焦點 | 本標準填補的缺口 |
|------|------|------------------|
| [documentation-structure.md](../../../core/documentation-structure.md) | 文件放在哪裡（目錄結構、命名） | 不處理更新時機 |
| [documentation-writing-standards.md](../../../core/documentation-writing-standards.md) | 如何撰寫文件（內容、風格、格式） | 不處理更新觸發條件 |
| **documentation-lifecycle.md**（本標準） | **何時更新、何時檢查、誰負責** | -- |

---

## 核心原則

### 共同更新原則

> **修改程式碼的人負責在同一個 PR 中更新對應的文件。**

文件更新不得延後到獨立的 PR 或後續的 sprint。當程式碼與文件脫節時，使用者會看到過時的資訊，修復成本也會隨時間增加。

**規則：**
- 程式碼變更與文件變更必須（MUST）在同一個 pull request 中
- 程式碼作者是文件更新的主要負責人
- 審查者應該（SHOULD）在程式碼審查時驗證文件的完整性

### 前移原則

> **越早發現文件問題，修復成本越低。**

```
修復成本
     ^
     |                                          ████ 發布
     |                              ████
     |                  ████ PR 審查
     |      ████
     | ████ Commit
     +-----------------------------------------> 時間
```

在 commit 階段偵測（秒級、自動化）遠比在 release 階段偵測（小時級、手動）成本低。下方的檢查金字塔透過從快速/自動化到全面/手動的分層檢查來實踐此原則。

此原則也與 **README 驅動開發**（Tom Preston-Werner）一致：先撰寫 README 可以在開始寫程式碼前釐清目的，在最早階段發現文件缺口。

### 恰到好處的文件

> **在敏捷環境中，撰寫能創造價值的文件。**（ISO/IEC 26515）

- 偏好活文件而非全面的預先文件
- 文件深度應與變更的風險和複雜度相匹配
- 聚焦於幫助下一位讀者（新開發者、未來維護者或終端使用者）做出決策或採取行動

---

## 文件更新觸發規則

### 觸發條件 x 文件類型矩陣

使用此矩陣判斷每種變更類型需要更新哪些文件。格子中標示義務等級。

| 觸發條件 | README | API 文件 | CHANGELOG | 架構文件（ADR） | 使用者指南 | 翻譯 |
|----------|:------:|:--------:|:---------:|:---------------:|:----------:|:----:|
| **新功能** | SHOULD | MUST | MUST | SHOULD | MUST | SHOULD |
| **API 變更** | N/A | MUST | MUST | SHOULD | SHOULD | SHOULD |
| **破壞性變更** | MUST | MUST | MUST | MUST | MUST | MUST |
| **Bug 修復** | N/A | N/A | SHOULD | N/A | SHOULD | N/A |
| **依賴升級** | SHOULD | N/A | SHOULD | SHOULD | N/A | N/A |
| **設定變更** | SHOULD | N/A | SHOULD | N/A | MUST | SHOULD |
| **架構變更** | SHOULD | SHOULD | MUST | MUST | SHOULD | SHOULD |

**圖例：**
- **MUST** -- 必要。PR 未完成此更新不應合併。
- **SHOULD** -- 建議。審查者標記缺失，但不阻擋合併。
- **N/A** -- 不適用於此觸發條件與文件類型的組合。

### 如何使用此矩陣

1. 識別您正在進行的變更類型（左欄）
2. 對每種文件類型（頂列），檢查義務等級
3. 將所有 MUST 更新包含在與程式碼變更相同的 PR 中
4. SHOULD 更新盡可能在同一 PR 中完成；否則建立後續 issue

---

## 文件檢查金字塔

檢查分為三個層級，從快速/自動化到全面/手動。

```
                ┌──────────────────┐
                │  Level 3         │  發布
                │  全面檢查         │  （小時級）
                ├──────────────────┤
            ┌───┴──────────────────┴───┐
            │  Level 2                 │  PR 審查
            │  半自動化                 │  （分鐘級）
            ├──────────────────────────┤
        ┌───┴──────────────────────────┴───┐
        │  Level 1                         │  Commit
        │  自動化                           │  （秒級）
        └──────────────────────────────────┘
```

### Level 1：Commit（自動化，秒級）

透過 pre-commit hooks 或 CI 在每次 commit 時自動執行。

| 檢查項目 | 類型 | 工具範例 |
|----------|------|----------|
| 內部連結有效性 | 硬檢查 | markdown-link-check, lychee |
| 參考檔案存在性 | 硬檢查 | 自訂腳本 |
| Markdown 語法有效性 | 硬檢查 | markdownlint, remark-lint |
| 版本標頭存在性 | 硬檢查 | 自訂腳本（grep） |

**目標：** 即時捕捉斷連結和結構問題。

### Level 2：PR 審查（半自動化，分鐘級）

在 pull request 審查期間執行，結合自動化檢查與人工判斷。

| 檢查項目 | 類型 | 方法 |
|----------|------|------|
| 文件-程式碼變更同步 | 硬檢查 | CI 腳本：偵測程式碼變更是否缺少對應文件更新 |
| 觸發矩陣合規性 | 軟檢查 | 審查者對照觸發矩陣驗證 |
| 內容準確性 | 軟檢查 | 審查者閱讀更新的文件 |
| 範例程式碼正確性 | 軟檢查 | 審查者抽查範例 |
| 術語一致性 | 軟檢查 | 審查者或 linter（vale, textlint） |

**目標：** 確保文件與程式碼變更保持同步。

### Level 3：發布（全面檢查）

在每次發布前作為發布檢查清單的一部分執行。

| 檢查項目 | 類型 | 方法 |
|----------|------|------|
| 版本號一致性 | 硬檢查 | 腳本：驗證所有版本參考是否一致 |
| 翻譯同步狀態 | 硬檢查 | 腳本：比較原始檔與翻譯檔的 hash |
| 功能-文件覆蓋率 | 硬檢查 | 腳本：計算功能數與已文件化的功能數 |
| 所有外部連結有效性 | 硬檢查 | 連結檢查工具（含外部 URL 驗證） |
| CHANGELOG 完整性 | 軟檢查 | 人工審查發布說明 |
| 遷移指南完整性 | 軟檢查 | 人工審查（如適用） |
| README 準確性 | 軟檢查 | 人工審查專案描述、徽章、範例 |
| 文件可用性抽查 | 軟檢查 | 驗證關鍵使用者路徑已記錄且範例可運作（靈感來自 ISO/IEC 26513） |

**目標：** 確保文件已準備好發布且完整。

---

## 硬檢查與軟檢查

每個檢查項目被分類為硬檢查或軟檢查。此區分決定了檢查是否能阻擋工作流程。

### 硬檢查（自動化，阻擋）

硬檢查是確定性的、可自動化的，並產生二元通過/失敗結果。

| 檢查項目 | 描述 | 自動化方式 |
|----------|------|-----------|
| 版本一致性 | 所有版本參考在檔案間一致 | 腳本比對 |
| 檔案存在性 | 參考的檔案存在於指定路徑 | 檔案系統檢查 |
| 連結有效性 | 內部和外部連結正確解析 | 連結檢查工具 |
| 翻譯同步 | 翻譯檔案與原始檔結構一致 | Hash 或標頭比對 |
| Markdown 語法 | 檔案通過 markdown lint 規則 | markdownlint, remark-lint |
| 功能數量正確性 | 文件中的功能數量與實際一致 | 自訂腳本 |

**特性：**
- 可實作為 CI/CD 管線步驟
- 產生確定性的通過/失敗結果
- 失敗時應該（SHOULD）阻擋合併或發布

### 軟檢查（人工，建議性）

軟檢查需要人工判斷，無法完全自動化。

| 檢查項目 | 描述 | 方法 |
|----------|------|------|
| 內容正確性 | 文件準確描述行為 | 人工審查 |
| 範例可運行性 | 程式碼範例可無錯誤執行 | 手動測試或 doctest |
| 發布說明準確性 | CHANGELOG 條目準確描述變更 | 人工審查 |
| 遷移指南完整性 | 遷移步驟涵蓋所有破壞性變更 | 人工審查 |
| 術語一致性 | 術語在全文中一致使用 | 人工審查或風格 linter |
| 可讀性 | 文件清晰且組織良好 | 人工審查 |

**特性：**
- 需要人工判斷或上下文理解
- 產生建議性建議，非二元結果
- 不應該（SHOULD NOT）自動阻擋合併，但應該（SHOULD）納入審查檢查清單

---

## 責任歸屬矩陣

此矩陣定義各文件類型的更新負責人、更新時機和驗證方式。

| 文件類型 | 主要負責人 | 更新時機 | 驗證方式 |
|----------|:----------:|:--------:|:--------:|
| README | 程式碼作者 | 與程式碼變更同一 PR | PR 審查（軟） |
| API 文件 | 程式碼作者 | 與 API 變更同一 PR | PR 審查 + 連結檢查（硬 + 軟） |
| CHANGELOG | 程式碼作者（條目）/ 發布管理者（最終版） | 條目：同一 PR；最終版：發布時 | 發布檢查清單（軟） |
| 架構文件（ADR） | 技術主管 / 架構師 | 做出架構決策時 | PR 審查（軟） |
| 使用者指南 | 程式碼作者 / 技術寫手 | 同一 PR 或後續 issue | PR 審查（軟） |
| 翻譯 | 翻譯者 / 程式碼作者 | 原始檔定稿後 | 翻譯同步腳本（硬） |
| 行內程式碼註解 | 程式碼作者 | 與程式碼變更同一 PR | PR 審查（軟） |
| 設定文件 | 程式碼作者 | 與設定變更同一 PR | PR 審查（軟） |

### 角色定義

| 角色 | 描述 |
|------|------|
| 程式碼作者 | 撰寫程式碼變更的開發者 |
| 審查者 | 審查 pull request 的人 |
| 技術主管 / 架構師 | 負責架構決策的資深工程師 |
| 發布管理者 | 負責發布流程的人 |
| 翻譯者 | 負責翻譯檔案的人 |
| 技術寫手 | 專職文件專家（如有） |

---

## 與其他標準的整合

本標準與以下標準協同運作：

| 標準 | 關係 |
|------|------|
| [documentation-structure.md](../../../core/documentation-structure.md) | 定義文件**放在哪裡**；本標準定義**何時更新** |
| [documentation-writing-standards.md](../../../core/documentation-writing-standards.md) | 定義**如何撰寫**文件；本標準定義**何時**和**誰** |
| [checkin-standards.md](../../../core/checkin-standards.md) | 包含「文件已更新」作為提交門檻；本標準提供詳細檢查清單 |
| [code-review-checklist.md](../../../core/code-review-checklist.md) | 包含「文件已更新？」審查項目；本標準提供觸發矩陣和責任分配 |
| [changelog-standards.md](../../../core/changelog-standards.md) | 定義 CHANGELOG 格式；本標準定義何時需要 CHANGELOG 更新 |

---

## 快速參考

### 決策流程圖

```
這是程式碼變更嗎？
├── 是 → 查閱觸發條件 × 文件類型矩陣
│         ├── 有 MUST 格子？→ 在同一 PR 中更新
│         ├── 有 SHOULD 格子？→ 盡可能在同一 PR 中更新
│         └── 全部 N/A？→ 不需要文件更新
└── 否（純文件變更）→ 遵循 documentation-writing-standards.md
```

### 最低可行文件檢查

適用於漸進式採用本標準的團隊：

| 階段 | 要實施的檢查 | 工作量 |
|------|-------------|--------|
| 階段 1 | 連結有效性（Level 1） | 低 -- 將 markdown-link-check 加入 CI |
| 階段 2 | 文件-程式碼同步偵測（Level 2） | 中 -- CI 腳本標記純程式碼 PR |
| 階段 3 | 完整觸發矩陣合規（Level 2-3） | 高 -- 審查者培訓 + 發布檢查清單 |

---

## 版本歷史

| 版本 | 日期 | 變更 |
|------|------|------|
| 1.0.0 | 2026-03-27 | 初版文件生命週期標準 |

---

## 授權

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