38 lines
1.3 KiB
Markdown
38 lines
1.3 KiB
Markdown
# DOC-001 先确定读者与阅读目标
|
|
|
|
分类：读者与定位。级别：核心。本规则是项目写作约定，不是语言语义。
|
|
|
|
## 规则
|
|
|
|
每次新增或改写页面，先写出目标读者、已知知识和读完后能够完成的事项。
|
|
|
|
## 原因
|
|
|
|
作者熟悉的内容不等于读者已经知道的内容；范围应由知识差距与任务决定。
|
|
|
|
## 执行方法
|
|
|
|
1. 在改动说明中记录读者与知识前提，不把这份内部记录塞入每个正文开头。
|
|
2. 用可检查的目标替换“详细介绍”，例如“能区分归属 key 与引用 key”。
|
|
3. 删去与目标无关的实现历史；必要的背景链接到主定义页。
|
|
|
|
## 改写对照
|
|
|
|
问题写法：本文详细介绍我们之前讨论的东西。
|
|
|
|
推荐做法：本文说明 namespace key 的组成、最小归属和引用关系。
|
|
|
|
以上是说明写作差异的项目例子，不新增语言能力。
|
|
|
|
## 验收
|
|
|
|
- [ ] 无需聊天历史即可确定主题。
|
|
- [ ] 页面能对应至少一个具体阅读目标。
|
|
- [ ] 没有默认读者理解团队内部代称。
|
|
|
|
## 依据与边界
|
|
|
|
[SRC-15](../research/SRC-15.md)、[SRC-14](../research/SRC-14.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。
|
|
|
|
[规则索引](../README.md#规则索引) · [检查清单](../checklist.md)
|