# 文档编写手册

本手册用于 Endorphin 文档的新增、修改和审查。它将外部案例分析转化为可执行的项目写作约定，不定义新的语言语义。

## 每次修改的入口

1. 阅读仓库 [AGENTS.md](../AGENTS.md) 与[工作流](workflow.md)。
2. 从下面的问题索引选择适用规则，阅读对应规则页；结构性改写至少检查 DOC-001、002、005、015、021、024。
3. 选择[页面模板](templates/README.md)，编辑主要定义与关联引用。
4. 使用[检查清单](checklist.md)，运行[文档检查工具](../tools/README.md)，记录结果。

小型错字修正不要求阅读全部 24 页；更改语法或章节结构必须覆盖其影响范围。手册规则与用户明确的语言决定冲突时，以用户决定为准并同步修订手册。

## 按问题查阅

| 正在解决的问题 | 规则 |
| --- | --- |
| 读者不知道这是什么，首页像约定清单 | [001](rules/DOC-001.md)、[003](rules/DOC-003.md) |
| 章节像聊天记录，教学、查询与争论混在一起 | [002](rules/DOC-002.md)、[018](rules/DOC-018.md) |
| 阅读时反复跳转，概念未介绍就出现 | [004](rules/DOC-004.md)、[005](rules/DOC-005.md) |
| 一章过大或分得过碎 | [006](rules/DOC-006.md) |
| 知道问题但找不到具体规则 | [007](rules/DOC-007.md)、[008](rules/DOC-008.md) |
| 示例不知道放哪里、没有结果或过于复杂 | [009](rules/DOC-009.md)、[010](rules/DOC-010.md)、[011](rules/DOC-011.md) |
| 只有成功用法，没有边界 | [012](rules/DOC-012.md)、[013](rules/DOC-013.md) |
| 多个概念或方案看起来一样 | [014](rules/DOC-014.md) |
| 不清楚哪些是提案，或正文充满免责声明 | [015](rules/DOC-015.md) |
| 语言用法混入系统实现 | [016](rules/DOC-016.md) |
| 名词、代码与输出记法不一致 | [017](rules/DOC-017.md)、[019](rules/DOC-019.md) |
| 外部建议无法核查，读不到页面 | [020](rules/DOC-020.md) |
| 改完一个章节后其他页面失配 | [021](rules/DOC-021.md) |
| 需要换电脑、换作者或让 AI 接续 | [022](rules/DOC-022.md)、[023](rules/DOC-023.md) |
| 工具检查都通过，但读者还是不懂 | [024](rules/DOC-024.md) |

## 规则索引

规则 ID 是稳定身份，不是阅读顺序。核心规则一般适用；建议规则按内容判断；条件规则只在对应情境使用。修改或废弃规则不重新分配其 ID。

| 编号 | 规则 | 分类 | 级别 |
| --- | --- | --- | --- |
| [DOC-001](rules/DOC-001.md) | 先确定读者与阅读目标 | 读者与定位 | 核心 |
| [DOC-002](rules/DOC-002.md) | 确定页面的主要职责 | 读者与定位 | 核心 |
| [DOC-003](rules/DOC-003.md) | 入口先建立全局理解 | 读者与定位 | 核心 |
| [DOC-004](rules/DOC-004.md) | 显式交代前置知识与上下文 | 读者与定位 | 核心 |
| [DOC-005](rules/DOC-005.md) | 按概念依赖安排阅读顺序 | 结构与导航 | 核心 |
| [DOC-006](rules/DOC-006.md) | 按读者问题分页 | 结构与导航 | 核心 |
| [DOC-007](rules/DOC-007.md) | 同时支持顺序阅读与按需查找 | 结构与导航 | 核心 |
| [DOC-008](rules/DOC-008.md) | 稳定编号与唯一主定义 | 结构与导航 | 核心 |
| [DOC-009](rules/DOC-009.md) | 最小示例必须有完整条件 | 示例与教学 | 核心 |
| [DOC-010](rules/DOC-010.md) | 形成代码、结果与解释的闭环 | 示例与教学 | 核心 |
| [DOC-011](rules/DOC-011.md) | 每个递进例子只增加少量新概念 | 示例与教学 | 建议 |
| [DOC-012](rules/DOC-012.md) | 把边界与失败写在相关规则旁 | 示例与教学 | 核心 |
| [DOC-013](rules/DOC-013.md) | 用可观察契约说明语义 | 语义与边界 | 核心 |
| [DOC-014](rules/DOC-014.md) | 比较方案时给出选择维度 | 语义与边界 | 条件 |
| [DOC-015](rules/DOC-015.md) | 区分确定规则、语法提案与未定边界 | 语义与边界 | 核心 |
| [DOC-016](rules/DOC-016.md) | 区分语言模型与实现机制 | 语义与边界 | 核心 |
| [DOC-017](rules/DOC-017.md) | 统一术语与展示记法 | 表述与证据 | 核心 |
| [DOC-018](rules/DOC-018.md) | 使用独立成立的文档陈述 | 表述与证据 | 核心 |
| [DOC-019](rules/DOC-019.md) | 让格式服务理解与查找 | 表述与证据 | 建议 |
| [DOC-020](rules/DOC-020.md) | 证据、分析与项目规则分层 | 表述与证据 | 核心 |
| [DOC-021](rules/DOC-021.md) | 每次改动完成影响检查 | 协作与质量 | 核心 |
| [DOC-022](rules/DOC-022.md) | 把文档作为可迁移的仓库资产 | 协作与质量 | 核心 |
| [DOC-023](rules/DOC-023.md) | 为人工与 AI 作者规定相同交付标准 | 协作与质量 | 核心 |
| [DOC-024](rules/DOC-024.md) | 用读者任务验收文档 | 协作与质量 | 核心 |

## 研究与应用

- [来源登记](research/sources.md)：15 个来源的 URL、类别与访问状态，其中 13 个由用户提供，2 个为补充方法资料。
- [分析总览](research/synthesis.md)：为什么这些做法有用，以及不应照搬什么。
- [当前文档的应用评估](adoption.md)：基线检查、剩余问题与后续改写优先级。
- [维护记录](CHANGELOG.md)：手册自身的变更及未读来源的补充状态。
- [贡献流程](../CONTRIBUTING.md)：跨电脑和多作者协作。

研究页区分可观察做法与作用推断。没有进行用户可用性实验，不把分析写成已验证的阅读效率。不可读来源不参与观点归纳。

[语言文档入口](../README.md)