docs(cfg): 配置设计档补示例文件一章,写作规范补单篇自洽原则
配置文件设计.md 增加第 2 章「一份完整示例文件」:给出首启模板全文 (8 段 46 键,值全部对照工厂默认宏核对),再按段拆成 2.1~2.6 六张 键表(键 / 类型 / 出厂值 / 含义 + 生效时机),读者不必再翻别的文档 才能知道每个段的键是什么意思。 为保持文档自洽顺带收敛: - 删掉文件格式章里重复的文件头代码块,改为指向第 2 章 - 删掉段表下「默认值见网络配置说明」的跳转,默认值现就在本篇 - 相关文档里把网络配置说明降级为对外使用手册 - 后续章号整体后移一位,交叉引用同步校准 doc-writer 角色补写作原则:原「同一事实只写一次」只覆盖跨篇去重, 照字面执行会逼出一篇到处跳转的文档。改为明确两条的分工——同一篇内 求完整、篇与篇之间求唯一,并给出判断标准(读者会不会被逼着另开一篇 才能读懂)与常见取舍。反模式表同步加一行。 验证:48 个提交期钩子全通过;check_doc_links / check_mermaid 通过。
This commit is contained in:
@@ -66,11 +66,13 @@ Diátaxis 是当前技术写作领域最具影响力的信息架构方法论,
|
||||
- **金字塔结构**:结论/摘要在前,细节在后
|
||||
- **镜像代码结构**:参考文档的章节层级应与源码目录/模块结构一致
|
||||
|
||||
### 3.2 单一真相源与引用锚点稳定性
|
||||
### 3.2 单篇自洽、跨篇去重(两条原则的适用边界)
|
||||
|
||||
- **同一事实只写一次**:其余位置通过链接、包含或代码生成引用
|
||||
- **锚点选择优先级**:函数名/宏名 > 文件路径 > 行号。行号随重构频繁失效
|
||||
- **引用完整性门禁**:自动化脚本校验所有内部链接指向的目标是否存在
|
||||
- **同一事实只写一次**:这是**跨篇**的规则——两个文件不要各写一遍同一个事实,其余位置用链接引用。
|
||||
- **单篇必须自洽**:这是**同一篇内**的规则——读者打开一篇文档,就应该能读懂这篇讲的事,不被逼着再翻三四篇。凡是理解本篇主线所必需的内容(关键数据结构长什么样、字段含义、出厂值、机制全貌),**完整写在这一篇里**,不要用"详见另一篇"打发。
|
||||
- 两条并不冲突,分工是:**同一篇内求完整,篇与篇之间求唯一**。判断标准是"读者会不会被逼着另开文档才能读懂这一段"——会,就必须挪进来或补上。
|
||||
- 常见取舍:把散落在别处的键表/默认值/示例整体搬进主文档,原处改成一句指向;次要细节(历史过程、外部硬件手册、使用流程)仍留给链接。
|
||||
- **锚点选择优先级**:函数名/宏名 > 文件路径 > 行号。行号随重构频繁失效,引用完整性由 `doc-links` 自动化门禁兜住。
|
||||
|
||||
### 3.3 生成器驱动文档
|
||||
|
||||
@@ -100,6 +102,7 @@ Diátaxis 是当前技术写作领域最具影响力的信息架构方法论,
|
||||
| 内部黑话/缩写未解释 | 新成员或跨团队读者无法理解 | 术语表 + 首次出现全称注释 |
|
||||
| 行号锚点重构后失效 | `file.c#L42` 指向的代码已移位 | 改用函数名/宏名锚点 |
|
||||
| 多份文档记录同一事实 | 两处数值不一致,不知哪个为准 | 单一真相源 + 引用/生成 |
|
||||
| 一篇讲不完、全靠跳转 | 读懂一段要另开三四篇,读者被逼着做知识拼图 | 单篇自洽:主线所需的键表/默认值/示例写进本篇,链接只留给次要细节 |
|
||||
| 混合文档类型 | 教程里塞入大段 API 参考 | Diátaxis 四象限分类,一篇一责 |
|
||||
| 事后补文档 | 记忆衰减导致遗漏关键设计决策 | 文档先行 + 问题即时记录 |
|
||||
|
||||
@@ -139,8 +142,9 @@ Diátaxis 是当前技术写作领域最具影响力的信息架构方法论,
|
||||
1. **每节第一句先答"我该干什么、为什么"**:实测值与出处只作从句证据。
|
||||
2. **不许有未解释的内部速记/缩写/裸小节号**:用户点名「黑话难懂」,每个术语首次出现必须解释。
|
||||
3. **不要写死源码行号**:定位代码改用「文件路径 + 函数名」当锚点,重构后不会漂移。
|
||||
4. **同一事实只在一处详述**:其他地方用链接引用,反对制造第二真相源。
|
||||
5. **待办「完成即销项」**:修复/关闭后直接从表中删除该行,不保留"已消化"行。新条目用**语义短语**标识,不再发字母+数字编号。
|
||||
4. **同一事实只在一处详述(跨篇)**:两个文件不要各写一遍同一个事实,其他地方用链接引用,反对制造第二真相源。
|
||||
5. **单篇必须自洽(篇内)**:读者打开一篇就要能读懂它讲的事——理解主线所必需的结构、字段、默认值、示例都写在这篇里,不要用"详见另一篇"打发。篇内求完整、篇间求唯一,两条合用。
|
||||
6. **待办「完成即销项」**:修复/关闭后直接从表中删除该行,不保留"已消化"行。新条目用**语义短语**标识,不再发字母+数字编号。
|
||||
|
||||
### 格式要求
|
||||
1. **编码 UTF-8 无 BOM**:中文文档一律 UTF-8,不带 BOM。
|
||||
|
||||
Reference in New Issue
Block a user