tech-doc-writer（技术文档作家）

技术学习文档写作 Skill

本 skill 指导如何写高质量、结构清晰、内容详细的技术学习文档（markdown 格式），适用于深度学习、机器学习、算法原理等技术主题。风格参考：激活函数文档、归一化方法文档。

核心目标：确保文档内容全面、及时反映技术最新发展，避免遗漏重要的新兴技术和实践。

核心写作流程

Step 1：信息收集

如果用户提供了参考文章 URL，先获取原文内容，然后：

1. 识别原文覆盖的知识点
2. 获取当前系统时间,找出原文的错误、缺失、过时的内容
3. 结合自身知识补充原文没有的重要内容，特别是最新的技术发展和实践

重要原则：不是"翻译"原文，而是以原文为基础，用自己的理解重写和扩充，确保内容的全面性和时效性。 特别注意：对于技术领域的文档，要重点关注近 3-5 年内的重要进展，如大模型中使用的 RMSNorm、SwiGLU 等新兴技术。

Step 1.5：穷举知识点 Checklist（⚠️ 强制步骤，不可跳过）

这是防止内容遗漏的核心机制。 过去的教训：直接进入写作模式会导致「写作驱动」而非「规划驱动」，靠「想到什么写什么」会遗漏非显眼但重要的技术点（如 MMR、RAG-Fusion、Semantic Cache 等）。

在动笔之前，必须先完成以下 3 个动作：

动作 1：按维度分类，穷举所有候选技术点

对文档主题，按照以下维度系统扫描，列出所有相关技术点：

维度扫描框架（根据主题调整）：

- 算法/方法类：基础方法 + 变体 + 新兴方法
- 工程实现类：库/框架 + 工具 + 部署
- 评估/对比类：指标 + 基准测试 + 对比维度
- 优化/改进类：性能优化 + 成本优化 + 质量优化
- 生态/周边类：相关工具 + 集成方案

动作 2：参照权威来源交叉验证，防止遗漏：

• 主流框架文档的 API/模块目录（最完整的技术地图，如 LangChain Retrievers 文档）
• 最新 Survey 论文的技术分类表
• 相关 GitHub Awesome 列表

动作 3：将所有技术点组织为带复选框的 Checklist

示例（RAG 主题）：

【分块策略】
□ 固定字符分块
□ 递归字符分块
□ Token 分块
□ 语义分块
□ 父文档检索
□ 命题分块          ← 容易遗漏（偏论文，不如框架API显眼）

【检索方式】
□ 纯向量检索
□ BM25 关键词检索
□ 混合检索 + RRF
□ MMR 多样性检索    ← 容易遗漏（解决多样性，方向与精度类不同）
□ Metadata Filtering ← 容易遗漏（工程技巧，不像算法显眼）

【查询增强】
□ Multi-Query
□ RAG-Fusion        ← 容易遗漏（与 Multi-Query 相似，常被合并忽视）
□ HyDE
□ Step-Back Prompting

【工程优化】
□ Semantic Cache    ← 容易遗漏（工程优化类，非核心算法）
□ 增量更新策略

完成 Checklist 后，对照着写文档，每完成一项打勾。 最终检查未打勾的项是否有意跳过还是遗漏。

Step 2：确定文档结构

每篇技术文档必须包含以下模块（按需取舍）：

通用结构（算法/框架类）：

1. 引言（为什么需要 XXX）
2. 统一视角 / 核心框架（用一个视角统一理解所有方法）
3. 各方法详解（每个方法独立一节）
4. 方法对比表（综合横向比较）
5. 选择指南 / 决策树（实用建议）
6. 代码示例（PyTorch / Python）
7. 参考资料

命令行工具专属结构（⚠️ 如文档主题是 CLI 工具/命令行程序，必须额外包含参数完整索引章节）：

1. 引言（工具简介、与其他工具对比、安装）
2. 核心概念（命令/子命令体系、配置文件等）
3. 各子命令详解（每个子命令独立一节，含常用选项示例）
4. 配置详解（配置文件格式、优先级等）
5. 工程集成（CI/CD、编辑器、预提交钩子等）
6. 最佳实践与常见陷阱
N-1. 参数完整索引（⚠️ 必须包含，见下方格式规范）
N.   参考资料

判断标准：文档主题涉及命令行工具（如 ruff、curl、git、uv、docker、kubectl 等）时，必须包含「参数完整索引」章节作为倒数第二章节。

工具/框架类专属结构（⚠️ 如文档主题是有配置项的工具/框架，必须包含环境变量章节）：

判断标准：文档主题涉及有环境变量支持的工具/框架（如 uv、docker、node、python、git 等）时，必须包含「环境变量」章节，完整列出所有支持的环境变量。

环境变量章节规范：

• 位置：放在「安装与配置」章节内，或作为独立章节（配置后、实战案例前）
• 分组：按功能分组（如「路径/目录」「网络/代理」「认证」「行为控制」等）
• 格式：每组一张 3 列表格 变量名 | 说明 | 示例/默认值，重要变量标注加入版本
• 完整性：必须覆盖官方文档的全部环境变量，不可只列「常用」的几个
• 弃用标注：已弃用的变量须注明 ⚠️ 已弃用及替代变量
• 外部变量：除工具自身定义的变量外，还需列出工具读取的外部系统变量（如代理、TLS 证书等）

### X.X 环境变量（完整列表）

> 官方参考：https://docs.xxx.xxx/reference/environment/

#### X.X.1 <工具名> 自身定义的环境变量

**📁 路径与目录**

| 变量 | 说明 | 示例/默认值 |
|------|------|-----------|
| `TOOL_CACHE_DIR` | 缓存目录 | `~/.cache/tool` |

**🌐 网络与代理**

| 变量 | 说明 | 示例/默认值 |
|------|------|-----------|
| `TOOL_HTTP_TIMEOUT` | HTTP 超时（秒） | `30` |

#### X.X.2 <工具名> 读取的外部变量

| 变量 | 说明 |
|------|------|
| `HTTP_PROXY` | HTTP 代理 |
| `HTTPS_PROXY` | HTTPS 代理 |

#### X.X.3 使用示例

示例注释

TOOL_VAR=value tool command

Step 3：写各方法详解

每个方法/概念的详解必须包含：

• 论文出处：作者、机构、年份、论文名
• 提出动机：解决什么问题（why）
• 数学定义：完整公式（LaTeX 格式）
• 导数 / 梯度：反向传播必要信息
• 直觉解释：用类比或图示帮助理解（why it works）
• 优点表格：结构化列出
• 缺点表格：结构化列出，包含已知的反驳/修正
• 适用场景：具体的任务、架构、数据类型
• 代码示例：可运行的代码片段

Step 4：补充原文没有的视角

优先添加以下高价值内容：

1. 统一理论框架：如"所有归一化方法的本质区别是在哪个维度做统计"
2. 历史演进脉络：用时间线梳理技术发展，突出技术迭代的逻辑
3. 已被推翻的叙事：如"BN 有效不是因为解决了 ICS，而是平滑了损失曲面"
4. 现代实践：最新的大模型 / SOTA 方法在用什么（如 RMSNorm、SwiGLU、LayerNorm 的变体等）
5. 新兴技术覆盖：重点关注近 3-5 年内提出的重要技术，确保文档反映技术前沿
6. 跨领域应用：不同领域（如 NLP、CV、生成模型）中归一化方法的选择差异
7. 常见陷阱：实践中容易踩的坑（如 PyTorch BN 的 momentum 定义与数学相反）
8. 决策树：帮助读者快速找到适合自己场景的方法

Step 5：写综合对比表

必须包含横向对比表，列出：

Step 6：分步输出（⚠️ 强制步骤）

对于大型技术文档（预计超过 500 行 / 5 个以上章节），必须采用分步输出策略：

1. 建立 todo list，将文档拆分为 5~8 个 Part，每个 Part 对应 1~2 个章节
2. 每次只输出一个 Part，完成后立即继续下一个 Part，无需等待用户催促
3. 自动推进：每个 Part 完成后，标记 todo 为 completed，立即开始下一个
4. 告知进度：在每个 Part 开头说明"当前是第 X/N 部分"

原因：一次性生成过长内容容易截断、遗漏章节、丢失上下文。分步输出确保每部分质量，也让用户实时看到进展。

1. 结构完整性校验（⚠️ 强制）：所有 Part 写完后，执行以下命令验证章节结构：

   grep -n "^## " 文档文件名.md

确认输出中章节编号从 1 开始连续递增，无跳号、无缺失。若发现如「第3章后直接是第8章」的跳号，必须立即补全缺失章节，再进行后续输出。

Step 7：完成后遗漏自检（⚠️ 强制步骤）

文档全部写完后，必须执行一次遗漏自检，步骤如下：

1. 列出文档现有的所有章节/技术点（grep "^### \|^####" 扫描）
2. 重新过一遍 Step 1.5 的 Checklist，逐项确认是否已覆盖
3. 重点核查容易遗漏的维度：

- 工程优化类（缓存、增量更新、可观测性） - 多样性/效率类（与主流精度类方向不同） - 新兴/小众但重要的技术（近 1~2 年新提出）

1. 若发现遗漏，立即补充到对应章节

教训：本规则来自实际 RAG 文档写作经验——初版遗漏了 MMR、RAG-Fusion、Semantic Cache、Multi-Vector Index、ColBERT、LLMLingua 等多项重要技术，均在事后检查中发现补充。

格式规范

数学公式

• 所有公式使用 LaTeX 格式
• 行内公式：$f(x) = ...$
• 块级公式：$$f(x) = ...$$
• 必须给出导数/梯度公式（反向传播需要）
• 重要变量要注解其含义

**数学定义：**

$$\sigma(x) = \frac{1}{1 + e^{-x}}$$

**导数：**

$$\sigma'(x) = \sigma(x)\big(1 - \sigma(x)\big)$$

代码示例

• 使用 Python / PyTorch（深度学习场景）
• 代码要可运行，包含必要的 import
• 加中文注释
• 示例要体现实际使用场景，而非只是 API 调用

# 示例：SwiGLU（LLaMA FFN 层）
class SwiGLU(nn.Module):
    """LLaMA / PaLM 使用的前馈层，用 SwiGLU 替代标准 FFN"""
    def __init__(self, in_dim, hidden_dim):
        super().__init__()
        self.w1 = nn.Linear(in_dim, hidden_dim, bias=False)
        self.w2 = nn.Linear(hidden_dim, in_dim, bias=False)
        self.w3 = nn.Linear(in_dim, hidden_dim, bias=False)

    def forward(self, x):
        # SiLU(xW1) ⊙ (xW3)，再经过 W2 投影
        return self.w2(F.silu(self.w1(x)) * self.w3(x))

ASCII 图示

对于维度关系、架构结构，使用 ASCII 图增强可视化：

        N (Batch)
        │
  ┌─────┼─────┐
  │ S1  │ S2  │
  └──┬──┘──┬──┘
     │  C  │
  ┌──┴──┐
  │ch1  │ch2│  H×W
  └─────┴───┘
  
BN: 在 N×H×W 上统计（跨样本）
LN: 在 C×H×W 上统计（跨通道）

表格规范

优缺点用结构化表格，不用列表：

| 优点 | 说明 |
|------|------|
| 加速训练 | 允许更大学习率，收敛快 |
| 正则化效果 | mini-batch 噪声类似 Dropout |

参数完整索引规范（CLI 工具文档专用）

当文档主题为命令行工具时，倒数第二章节必须是「参数完整索引」，按功能分组，每个分组一张 4 列表格。

列顺序：短参数 | 长参数 | 说明 | 示例

格式要求：

• 无短参数的行，短参数列留空（不写 — 或 /）
• 示例列必须是可直接运行的完整命令片段
• 同一子命令的参数按「修复/输出/规则选择/文件选择/其他」等功能子分组，用 #### 小标题分隔
• 子命令本身单独列一张「子命令一览」表，包含「子命令 / 说明 / 是否修改文件 / 示例」4 列

标准模板：

## N. 参数完整索引

> 按功能分类整理所有常用参数，便于快速查阅。

### N.1 子命令一览

| 子命令 | 说明 | 是否修改文件 | 示例 |
|--------|------|------------|------|
| `check` | 执行 lint 检查 | 否（`--fix` 时是） | `ruff check .` |
| `format` | 执行代码格式化 | 是（`--check` 时否） | `ruff format .` |

### N.2 全局选项

| 短参数 | 长参数 | 说明 | 示例 |
|--------|--------|------|------|
| `-v` | `--verbose` | 启用详细日志 | `-v` |
| | `--config <FILE>` | 指定配置文件 | `--config ruff.toml` |

### N.3 <子命令名> 选项

#### 修复相关

| 短参数 | 长参数 | 说明 | 示例 |
|--------|--------|------|------|
| | `--fix` | 应用安全修复 | `ruff check --fix .` |

参考示例：见 zwy/stats/py_base/002_doc_ruff.md 第 9 章、zwy/stats/shell/004_doc_curl_wget_shell.md 第 10 章。

引用、警告块

用 blockquote 标注重要修正或补充：

> **重要修正**：后续研究表明，BN 的有效性主要来自平滑损失曲面，
> 而非解决 ICS——这是对原始论文叙事的重要修正。

质量检查清单

写完文档后，获取当前系统时间,仔细检查文档，简单梳理结构，看看是否有过时内容，遗漏内容和改进的地方,未解释的缩写或名词,并进行改进。 然后逐项确认：

【分步输出检查（Step 6 相关）】

• [ ] 大型文档已建立 todo list 并分 Part 输出
• [ ] 每个 Part 完成后立即自动继续下一 Part，未等待用户催促
• [ ] 用 grep -n "^## " 扫描最终文件，验证章节编号从 1 开始连续递增，无跳号、无缺失

【完成后遗漏自检（Step 7 相关）】

• [ ] 已用 grep 扫描当前文档所有章节，重新过 Checklist
• [ ] 已重点核查「工程优化类」是否有遗漏
• [ ] 已重点核查「多样性/效率类」是否有遗漏
• [ ] 已重点核查「近 1~2 年新技术」是否有遗漏

【防遗漏检查（Step 1.5 相关）】

• [ ] 写作前已完成维度化穷举 Checklist（Step 1.5）
• [ ] 已对照框架文档/Survey 论文的模块目录交叉验证
• [ ] Checklist 中所有条目均已有意决定（写入文档 or 明确标注跳过原因）
• [ ] 检查是否遗漏「工程优化类」技术（如缓存、增量更新等，常被算法类掩盖）
• [ ] 检查是否遗漏「多样性/效率类」技术（与主流精度类方向不同，易被忽视）

【内容质量检查】

• [ ] 每个方法都有完整的数学公式（含导数）
• [ ] 每个方法都有代码示例（可运行）
• [ ] 包含综合对比表
• [ ] 包含选择指南/决策树
• [ ] 补充了原文缺失的重要方法（如 RMSNorm、SwiGLU 等现代方法）
• [ ] 重点覆盖了近 3-5 年内的重要技术进展
• [ ] 指出了原文的错误或过时信息
• [ ] 有直觉解释（不只是公式堆砌）
• [ ] 提到了实际使用中的陷阱
• [ ] 参考了最新的 SOTA 实践
• [ ] 考虑了跨领域应用的差异

【CLI 工具文档专项检查】

• [ ] 文档主题是 CLI 工具时，已包含参数完整索引章节（倒数第二章）
• [ ] 参数索引表列顺序为「短参数 / 长参数 / 说明 / 示例」
• [ ] 无短参数的行，短参数列留空（不写 —）
• [ ] 每行示例列为可直接运行的命令片段
• [ ] 参数按功能分组，用 #### 小标题分隔（修复/输出/规则选择/文件/其他）
• [ ] 包含子命令一览表（含「是否修改文件」列）

【环境变量章节检查（有环境变量支持的工具/框架类文档专用）】

• [ ] 已包含环境变量完整列表章节（不仅仅是「常用」几个）
• [ ] 环境变量按功能分组，每组一张 3 列表格
• [ ] 已弃用的变量已标注 ⚠️ 并注明替代变量
• [ ] 列出了工具读取的外部系统变量（代理、TLS 证书、认证 token 等）
• [ ] 包含使用示例小节（至少 5 个实用场景）
• [ ] 变量来源于官方文档，而非仅凭记忆列举（关键变量需标注加入版本）

参考示例

详见 references/ 目录：

• references/activation-functions-example.md — 激活函数文档节选示例
• references/normalization-example.md — 归一化文档节选示例