44 lines
1.6 KiB
Markdown
44 lines
1.6 KiB
Markdown
# DOC-003 入口先建立全局理解
|
|
|
|
分类：读者与定位。级别：核心。本规则是项目写作约定，不是语言语义。
|
|
|
|
## 规则
|
|
|
|
介绍页先回答是什么、解决什么问题、有哪些核心概念，再提供学习与查询入口。
|
|
|
|
## 原因
|
|
|
|
读者先形成整体模型，之后才有位置安放细节。
|
|
|
|
## 执行方法
|
|
|
|
1. 第一段使用具体用途定义语言，不用特性口号替代定义。
|
|
2. 用少量核心概念展示应用模型；选择一个小例子，不在概览堆全部语法。
|
|
3. 列出顺序阅读、主题查询和作者协作的入口，说明各自服务谁。
|
|
|
|
## 改写对照
|
|
|
|
问题写法：首页以十几条限制和待定事项开头。
|
|
|
|
推荐做法：首页先介绍统一的声明与调用模型，再连接语言正文和作者手册。
|
|
|
|
以上是说明写作差异的项目例子，不新增语言能力。
|
|
|
|
## 验收
|
|
|
|
- [ ] 初次读者能复述用途。
|
|
- [ ] 读者知道从哪里继续。
|
|
- [ ] 概览没有变成全部规范的重复摘要。
|
|
|
|
## 具体应用
|
|
|
|
首页第一段建立对象与用途，随后给适用读者、当前文档性质和开始阅读路径。主要细节链接到章节，不能把所有作者约束堆到入口。
|
|
|
|
详见[指南任务](../tasks/TASK-02.md)与[入口与信息位置](../references/information-architecture.md)。
|
|
|
|
## 依据与边界
|
|
|
|
[SRC-01](../research/SRC-01.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。
|
|
|
|
[规则索引](../README.md#规则索引) · [检查清单](../checklist.md)
|