Technical Documentation Writing Guide

A comprehensive guide for writing detailed, understandable technical documentation that explains technology stacks thoroughly.

核心原则

1. 技术栈完整性原则

规则: 凡是在【技术栈】标题中列出的技术，必须在【🧠深层原理】部分详细解释。

Why: 用户明确反馈"既然你提到了一些技术栈，就要把涉及到的技术栈都解释一下，别出现写出来的技术栈没有被解释的情况"。

How to apply:

• 在编写每个章节时，先检查【技术栈】列出的所有项目
• 逐一在【🧠深层原理】中添加对应解释
• 使用代码示例、架构图、数据流说明来辅助解释

示例:

技术栈: PyYAML, Dict Mapping, Path Handling

深层原理中需要包含:
- PyYAML: yaml.safe_load()的工作原理、YAML格式特点
- Dict Mapping: Python字典的存储、访问、嵌套结构
- Path Handling: pathlib的跨平台特性、路径操作方法

2. 内容贴合项目原则

规则: 所有解释性内容必须贴合具体项目，不能是泛泛的技术说明。

How to apply:

• 引用项目中的具体文件路径（如 ultralytics-main/train.py）
• 使用项目中的实际代码片段
• 说明技术在本项目中的具体应用场景
• 举例时使用项目的业务场景（如疲劳检测）

3. 详细易懂原则

规则: “字数长一些无所谓，重在理解”。

How to apply:

• 每个技术点提供充分的背景知识
• 使用多个角度解释（原理+代码+应用）
• 适当使用类比和图示
• 覆盖边界情况和注意事项

文档结构规范

必须保留的标题格式

【技术栈】- 列出涉及的技术
【目的】- 说明本步骤的目的
【🔗 紧接上一步】- 说明输入来源
【🔗 传递下一步】- 说明输出去向
【🧠深层原理】- 详细技术解释
【💡 通俗人话讲解】- 使用类比解释
【💻 项目真实完整代码片段】- 代码示例

各部分写作要点

【技术栈】格式: 用逗号分隔的技术名称，如：

PyTorch nn.Module, YOLOv10 Dual-head Architecture, Model Initialization

【🧠深层原理】格式: 编号列表 + 代码块 + 解释

1. **技术名称**:
   ```语言
   代码示例

• 解释要点1
• 解释要点2

**【💡 通俗人话讲解】格式**: 使用生活中的类比

把XX比作"生活中的场景"。

概念1是"类比对象1":

• 相似点1
• 相似点2

概念2是"类比对象2":

• 详细类比说明

## 技术解释模板

### 框架/库解释模板

技术名称是做什么的（一句话定义）:

简单使用示例

• 核心概念1: 解释
• 核心概念2: 解释
• 在本项目中的应用: 具体说明

### 算法解释模板

算法名称的工作原理:

算法步骤或伪代码

• 输入: 说明
• 输出: 说明
• 时间复杂度: 说明
• 本项目的特殊处理: 说明

### 系统机制解释模板

机制名称架构:

架构图或流程图

• 组件1的作用
• 组件2的作用
• 数据流向
• 与其他组件的交互

## 常见技术栈解释检查清单

### A类 - Python/深度学习
- [ ] PyTorch nn.Module → 解释继承、forward、参数管理
- [ ] DataLoader → 解释批次加载、pin_memory、多进程
- [ ] YAML → 解释格式、解析、字典映射
- [ ] pathlib → 解释跨平台、路径操作

### B类 - 模型转换
- [ ] ONNX → 解释格式、算子映射、跨平台
- [ ] torch.jit.trace → 解释追踪原理、静态图

### C类 - Web开发
- [ ] Flask → 解释路由、请求响应、模板渲染
- [ ] Ajax/fetch → 解释异步、Promise、轮询
- [ ] Canvas → 解释绑制API、即时模式
- [ ] JSON → 解释解析、类型映射、序列化

### D类 - Android/移动端
- [ ] JNI → 解释类型映射、本地引用、全局引用
- [ ] NCNN → 解释张量、内存池、推理流程
- [ ] Handler/Looper → 解释消息循环、定时任务
- [ ] Binder → 解释IPC、服务调用
- [ ] NEON → 解释SIMD、向量化

## 审计流程

### 完成文档后的自查步骤
1. 读取文档全部内容
2. 提取每个章节的【技术栈】列表
3. 检查【🧠深层原理】中是否对每个技术都有解释
4. 标记遗漏的技术项
5. 补充解释

### 审计命令示例

1. Grep pattern=“### [.*]” → 找到所有章节标题
2. Grep pattern=“**【技术栈】**” → 找到技术栈声明
3. Grep pattern=“**【🧠深层原理】**” → 找到解释部分
4. 对比检查

## 文件大小处理

当文档文件过大时（超过256KB），使用分段读取：

Read with offset=1, limit=600 → 第一部分
Read with offset=600, limit=600 → 第二部分
…

使用TodoWrite跟踪多个需要修改的章节。

## 质量标准

### 优秀技术解释的标准
1. **完整性**: 覆盖技术栈列表中的每一项
2. **准确性**: 技术原理正确无误
3. **实用性**: 与项目实际代码关联
4. **可读性**: 层次分明，代码示例清晰
5. **深度**: 不仅有使用方法，还有底层原理

### 避免的问题
- 技术栈列表与解释内容不匹配
- 解释内容与项目无关（泛泛而谈）
- 解释过于简单（缺少深度）
- 缺少代码示例
- 类比不恰当或不清楚