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