文档撰写规范

在编写、修改或审查技术文档时，严格遵循以下准则，确保文档结构清晰、信息密度高、读者能快速定位所需内容。

1. 通用原则

1. 读者优先：文档服务于读者（使用者/维护者），而非作者。确保读者一次读懂，无需反复猜测。
2. 先结构后内容：确定文档类型（README / 技术专题 / API 参考 / 教程），按对应模板组织章节（见下文第 3-4 节）。
3. 信息密度：每一段、每一句都承载有用信息。避免"这个功能很重要"等无信息量的表述。
4. 一条链路讲到底：技术文档按"为什么 → 是什么 → 怎么用 → 注意事项"的顺序层层递进，不跳跃。

2. 文件组织

2.1 目录结构

project/
├── README.md                  # 项目主入口：简介、快速开始、移植指南
├── LICENSE                    # 许可证
├── docs/                      # 技术专题文档目录
│   ├── README.md              # 文档索引 + 推荐阅读顺序
│   ├── basic_principles.md    # 基础理论（如 FOC 原理）
│   ├── usage_guide.md         # 使用指南
│   ├── api_reference.md       # API 参考
│   └── advanced/              # 进阶专题子目录
│       ├── observers.md
│       └── ...
├── src/                       # 源代码
└── ...

2.2 命名规范

• 文件名：小写英文 + 下划线分隔（current_calibration.md、foc_basic_principles.md），与源码命名风格一致。
• 目录名：复数或集合名词（docs、observers）。
• 文档路径引用：始终使用相对路径 [text](./docs/file.md)，确保在 GitHub 和本地 IDE 中均可正确跳转。

3. README 模板

项目根目录 README.md 按以下结构组织，按需省略不适用的章节：

<div align="center">
    <h1>项目名称</h1>
    一句话描述（中文，突出核心特性）
</div>

---

## 项目架构

简要架构图（Mermaid flowchart），概述模块关系。

## 特性 / 功能

- 特性 1：简短说明
- 特性 2：简短说明
- ...

## 1. 添加到你的项目

### 1.1 在 XXX 平台添加

分平台说明集成步骤，附代码块。

### 1.2 在 YYY 平台添加

## 2. 快速开始 / 最小示例

提供可运行的最小代码示例，代码块需标注语言。

## 3. 详细使用教程

### 3.1 主题 A
### 3.2 主题 B
...

## 4. API / 配置参考

使用表格列出关键 API 或配置项。

## 5. 模式 / 模式切换

如有模式/策略设计，用表格列出模式矩阵。

## 故障排查 / FAQ

## 文档索引

链接到 `docs/` 下的技术专题文档。

## License

3.1 README 要点

• 开头 <div align="center">：用于项目 Logo 或标题醒目展示。
• 第二大块是架构图：让读者在 10 秒内理解项目的模块关系。
• 最小示例放在前面：降低读者获取价值的门槛，先跑通再深入。
• 表格优先于段落：API 列表、模式矩阵、参数说明用表格呈现，比连续段落更易扫读。
• 代码块必须标注语言：```c、```cmake。

4. 技术专题文档模板

docs/ 下的技术文档按以下结构组织：

# 文档标题

## 1. 背景 / 为什么需要

简要说明这个机制/算法/流程解决什么问题。

## 2. 原理

### 2.1 数学模型

公式、推导、图表（Mermaid 流程图）。

### 2.2 关键变量

| 符号 | 含义 | 来源 / 备注 |
|------|------|------------|
| ...  | ...  | ...        |

## 3. 使用方法

### 3.1 配置步骤

### 3.2 最小示例

代码块 + 注释说明。

### 3.3 参数说明

| 参数 | 类型 | 说明 | 推荐值 |
|------|------|------|--------|
| ...  | ...  | ...  | ...    |

## 4. 注意事项 / 约束

> 使用引用块突出关键约束。

- 不可在 ISR 中调用阻塞操作
- 必须先完成 X 再执行 Y
- ...

## 5. 故障排查

常见问题 + 原因 + 解决方案。

4.1 技术文档要点

• 数学公式：块公式用 $$ ... $$，行内公式用 $...$，行内公式前后与中文字符用空格隔开。详见 math-formula-guidelines。
• 参数表：必须包含"类型""说明""来源/推荐值"列，不可只有名称（读者需要知道怎么填）。
• Mermaid 图表：链路图、状态机、数据流优先使用 Mermaid，比截图更易维护和版本对比。
• 注意事项用引用块 >：与正文形成视觉区分，读者扫读时能快速定位关键约束。

5. 排版规范

5.1 中文文案

• 中文与英文/数字之间加半角空格：使用 ESP32 的 MCPWM，频率为 20 kHz。
• 中文与行内代码之间加空格：调用 `foc_tick()` 函数。
• 中文标点全角（。、，、；），英文标点半角（,、.、;）。
• 数字单位用空格分隔：20 kHz、1.65 V、0.01 Ω。

5.2 标题与章节

• 编号后有一个中文空格再接标题文字。
• 不跳过层级（不要从 ## 直接到 ####）。
• 章节之间用 --- 水平线分隔（可选，用于长文档的主要分区之间）。

5.3 代码块

• 必须标注语言：```c、```cmake、```mermaid。
• 嵌入式 C 代码内的注释使用 // 或 /* */，保持与项目源码风格一致。
• 长代码块超过 30 行考虑拆分为多个小块，或折叠次要部分。
• 代码块前后各留一个空行。

5.4 表格

• 表头用加粗，对齐用 |------|------| 分隔。
• 表内文字精炼，能用符号不用文字（如 ✅ ✗ 代替"支持""不支持"）。
• 表格前后各留一个空行。

5.5 引用块

• 使用 > 标记提示、警告、约束、引用。
• 重要约束放在相关章节的引用块中，而非埋在正文段落里。
• 多段引用用 > + 空行 > 连续。

5.6 链接

• 内部链接用相对路径：[text](./docs/file.md)。
• 标题锚点：[text](#32-校准流程配置)，注意 GitHub 会自动生成小写锚点、忽略标点、空格变 -。
• 外部链接用完整 URL，关键链接后标注语言/类型：[ESP-IDF 文档](https://docs.espressif.com/)（英文）。

6. 图表规范

6.1 Mermaid

• 流程图用 flowchart LR/TB，状态机用 stateDiagram-v2，时序用 sequenceDiagram。
• 节点文字使用中文，如仍有英文术语则保留原文。
• 图表应配有文字说明，不可只有图没有解释。

6.2 数学公式

• 遵循 math-formula-guidelines 中的规则。
• 块公式独立成行，前后各留一个空行。
• 行内公式的 $ 前后与中文字符之间加空格：电压 $V_m$ 越大。

7. 文档更新原则

• 代码即文档：API 文档应与头文件注释保持同步，头文件是 API 参考的第一来源。
• 修改代码同步更新文档：任何公共接口变更、新增模式、新增校准步骤，必须同步更新对应文档。
• 文档版本标注：如果文档涵盖版本相关的差异（如"v2.0 起支持"），用引用块标注：> 此功能自 v2.0 起可用。

8. 增量修改克制

更新已有文档时，优先在现有章节中追加内容，而非新增独立章节。

理由：增量修改比新增章节更易维护。读者不会在一堆分散的小节中找不到主线，LLM 扫描时也能更快定位。

判断是否需要新增章节：满足以下条件中的 ≥ 2 条 才值得开独立章节，否则在现有章节中追加即可。

正确——追加到现有章节：

<!-- 在功能列表中追加一行 -->
- 新增：XX 功能
<!-- 在命令表中追加一行 -->
| `/cmd` | 功能描述 |

错误——动辄新增独立章节：

## 5. 新功能 X

一个开关就能控制……（展开一整节）

9. 多语言文档同步

如果项目维护多份语言的文档（如 README.md + README_EN.md），修改任何文档时必须同步更新所有语言版本。

理由：不同语言的用户应看到一致的文档内容，避免信息不对称。中英双语项目应改一次改两处。

正确：

修改 README.md 的功能列表 → 同步更新 README_EN.md 的 Features 列表

错误：

只改 README.md，忘记同步 README_EN.md，导致英文版缺少新功能描述

提交前自检：所有语言的文档改动是否在同一 commit 中。

10. 自检要求

输出前请自检，如出现违反以上规则的输出，重新输出。