---
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) | [繁體中文](../../zh-TW/core/documentation-lifecycle.md) | 简体中文

# 文档生命周期标准

**版本**: 1.0.0
**最后更新**: 2026-03-27
**适用范围**: 所有具有文档的软件项目

---

## 目的

本标准定义文档的**何时更新**、**何时检查**、以及**谁负责**。它与现有文档标准互补：

| 标准 | 焦点 | 本标准填补的缺口 |
|------|------|------------------|
| [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/) 许可发布。
