51 lines
3.5 KiB
Markdown
51 lines
3.5 KiB
Markdown
# 文档案例分析总览
|
|
|
|
优秀文档的价值不在统一的外观，而在于读者能建立模型、完成当前任务、找到精确规则并核对结果。下表归纳不同页面的侧重；效果解释属于本项目分析，不是测量结论。
|
|
|
|
## 各案例的长处与边界
|
|
|
|
| 案例 | 可观察做法 | 值得借鉴的重点 | 不宜照搬 |
|
|
| --- | --- | --- | --- |
|
|
| [Vue / SRC-01](SRC-01.md) | 定义、示例、前提与学习入口 | 先形成全局认识 | 文件模型和多 API 风格 |
|
|
| [MDN / SRC-02](SRC-02.md) | 分类、表格、结果对照与参考链接 | 概念讲解和精确查询互相连接 | 非标准条目当作稳定规范 |
|
|
| [HTML / SRC-03](SRC-03.md) | 结构拆解、嵌套、例子解释 | 从小结构建立组合关系 | 标签语义移植到组件 |
|
|
| [React / SRC-04](SRC-04.md) | 交代容器、简化代码、展示结果 | 上下文与结果闭环 | 依赖文件与前章准备的形式 |
|
|
| [Rust / SRC-05](SRC-05.md) | 连续操作、条件与边界 | 少量新概念逐步加入 | 在本语言中引入对应 API |
|
|
| [Matplotlib / SRC-06](SRC-06.md) | 同任务接口对照与选择原因 | 概念差异用于判断 | 因比较而创造另一套语法 |
|
|
| [VS Code / SRC-07](SRC-07.md) | 目标分流、验证与人工审查 | 写作流程有职责边界 | 绑定特定编辑器、账号或模型 |
|
|
| [pandas / SRC-08](SRC-08.md) | 不同学习入口、记法与主题目录 | 多入口与展示规范 | 仅凭目录评价所有章节 |
|
|
| [scikit-learn / SRC-09](SRC-09.md) | 多层主题与实践、选择入口 | 大范围内容可定位 | 追求复杂编号或目录深度 |
|
|
| [Wikipedia / SRC-11](SRC-11.md) | 文档用途与维护方式分类 | 使用手册不等于实现记录 | 百科作为项目强制标准 |
|
|
| [Diátaxis / SRC-14](SRC-14.md) | 按需求区分文档职责 | 先决定页面要做什么 | 为分类复制整套内容 |
|
|
| [Google / SRC-15](SRC-15.md) | 读者背景与学习目标 | 按知识差距选解释 | 作者自查冒充读者实验 |
|
|
|
|
[三个知乎记录](sources.md)未取得正文，不在该比较中评价其优劣。
|
|
|
|
## 对 Endorphin 的综合方法
|
|
|
|
### 让主线服务理解
|
|
|
|
身份和 namespace 是程序定位的前提；程序结构、阶段、类型和表达式支持后续调用与 UI 用法。章节顺序由这些关系决定，而不是研发议题出现的顺序。
|
|
|
|
### 让参考服务查询
|
|
|
|
一份主定义、一套完整文法、稳定规则 ID、术语和主题索引共同支持跳转阅读。结构精简不是删除必要条件；局部页面仍需要最小上下文。
|
|
|
|
### 让例子服务迁移
|
|
|
|
采用声明、输入、结果与关键解释的闭环。逐步组合少量概念，在触及边界时说明失败。源码、展示结果与提案状态必须可区分。
|
|
|
|
### 让写作与语言决定分离
|
|
|
|
文档可以采用确定的编写规范，同时保持语言处于设计稿阶段。官方引用、get、等待和错误处理等未定项不能因为页面要写得流畅而被擅自确认。
|
|
|
|
### 让维护可复现
|
|
|
|
每次修改选择适用规则，检查关联章节，再运行工具并完成读者任务自查。版本控制保存变更；真实读者测试、语法检查与运行测试分别报告。
|
|
|
|
## 尚需验证的效果
|
|
|
|
本研究尚未证明上述方法提高了真实读者的理解或定位速度。后续评估可让未参与设计的人完成冷读、找规则和预测结果任务，记录具体障碍，再调整页面。检查方案见 [DOC-024](../rules/DOC-024.md)。
|
|
|
|
[手册入口](../README.md)
|