108 lines
8.4 KiB
Markdown
108 lines
8.4 KiB
Markdown
# 文档编写手册
|
|
|
|
本手册用于 Endorphin（对话中也称 Endor）文档的编写、修改与审查。它同时是 `endor-docs` skill 的完整资源包：从本次任务选择方法，读对应小节，再写作和验收。正式名称、语法及语言决定以目标仓库的主定义为准。
|
|
|
|
## 每次修改的入口
|
|
|
|
1. 阅读目标仓库 AGENTS.md 与 [SKILL.md](SKILL.md)，确定读者要完成的判断或操作。
|
|
2. 从下面选择主任务及补充任务；查询并阅读对应任务页、方法、DOC 规则与相关语言主定义。
|
|
3. 参考完整案例，选择合适的页面模板，先写主要定义，再同步依赖内容。
|
|
4. 按[工作流](workflow.md)完成影响检查，用[审查标准](references/review-rubric.md)判断是否达到目标，记录实际验证。
|
|
|
|
每次工作都要选择对应路线；小型错字不要求通读手册。多个任务可以合并，例如“深化函数章节并补例子”使用 guide + example。用户明确的新语言决定优先于旧稿，按语义变更路线落实准确范围。
|
|
|
|
## 按任务进入
|
|
|
|
| 本次工作 | 路线 | 实际要得到什么 |
|
|
| --- | --- | --- |
|
|
| 修正措辞、术语、链接或错字 | [edit / TASK-01](tasks/TASK-01.md) | 保留语义的局部修正及必要联动 |
|
|
| 新写、深化或标准化一章 | [guide / TASK-02](tasks/TASK-02.md) | 可顺序读懂的完整指南 |
|
|
| 写语法、参数和行为查询说明 | [reference / TASK-03](tasks/TASK-03.md) | 可独立查询的形式、条件与效果 |
|
|
| 补全、修复或统一示例 | [example / TASK-04](tasks/TASK-04.md) | 有上下文、声明、输入与结果的例子 |
|
|
| 调整目录、分页或定义位置 | [structure / TASK-05](tasks/TASK-05.md) | 职责清楚的结构及同步导航 |
|
|
| 落实语言决定、修复语义冲突 | [semantics / TASK-06](tasks/TASK-06.md) | 主定义、文法、状态与例子一致 |
|
|
| 评审质量或查找问题 | [review / TASK-07](tasks/TASK-07.md) | 有证据、可直接实施的发现 |
|
|
| 研究来源、改进手册和 skill | [research / TASK-08](tasks/TASK-08.md) | 解决具体写作缺口的方法与验证 |
|
|
|
|
选择任务后，直接打开该页列出的必读方法、规则和示例；涉及语言断言时再查下面的语言核对地图。每次实际阅读对应小节与注意事项，不能只记录规则编号。
|
|
|
|
[使用与跨电脑接续](skill-usage.md)说明项目级 skill 入口和可迁移方式。整个流程通过 Markdown 查阅完成；程序、脚本和测试只在用户明确要求执行时运行。
|
|
|
|
## 具体方法与成稿示范
|
|
|
|
| 作者需要作出的判断 | 方法 | 示例 |
|
|
| --- | --- | --- |
|
|
| 当前语言断言是否有依据，哪个维度仍未确定 | [语言核对地图](references/language-map.md) | [有证据的审稿](examples/EX-04.md) |
|
|
| 一页放什么、何时拆页、如何安排前提 | [信息架构](references/information-architecture.md) | [章节重组](examples/EX-05.md) |
|
|
| 语法怎样写成合法性与行为说明 | [语义契约](references/semantic-contracts.md) | [use 参考成稿](examples/EX-02.md) |
|
|
| 示例怎样同时做到小、完整、可解释 | [示例设计](references/example-design.md) | [跨 namespace 调用](examples/EX-03.md) |
|
|
| 中文说明怎样独立成立且容易检索 | [中文表达与记法](references/chinese-style.md) | [身份指南改写](examples/EX-01.md) |
|
|
| 何种问题必须修复，怎样证明完成 | [审查与验收](references/review-rubric.md) | [具体审查发现](examples/EX-04.md) |
|
|
|
|
案例包含原稿、判断、成稿及验收；方法页解释会改变写作决策的条件。24 条 DOC 原则保留稳定编号，承担快速查询与审查依据。
|
|
|
|
## 按问题查阅
|
|
|
|
| 正在解决的问题 | 规则 |
|
|
| --- | --- |
|
|
| 读者不知道这是什么，首页像约定清单 | [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)：手册自身的变更及未读来源的补充状态。
|
|
- [行为评估场景](evaluation/scenarios.md)：验证 skill 的任务选择、语义判断和实际产物。
|
|
- [本次评估记录](evaluation/results-2026-10-08.md)：作者走查、实际产物及验证范围。
|
|
- [贡献流程](../CONTRIBUTING.md)：跨电脑和多作者协作。
|
|
|
|
研究页区分可观察做法与作用推断。没有进行用户可用性实验，不把分析写成已验证的阅读效率。不可读来源不参与观点归纳。
|
|
|
|
[语言文档入口](../README.md)
|