Endorphin-Document/authoring/README.md

文档编写手册

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

每次修改的入口

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

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

按问题查阅

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

规则索引

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

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

研究与应用

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

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

语言文档入口