2.8 KiB
TASK-02 新增或深化指南
适用：新章节、首页介绍、补全一个概念，或将对话式草稿改成可顺序阅读的指南。
必读：信息架构、中文表达、DOC-001、DOC-002、DOC-004、DOC-005、DOC-015。模板按用途选择 TPL-01、TPL-02或TPL-04。
从“详细写一下”到明确的学习目标
把主题拆成读者需要作出的判断。例如用户身份章节可让读者：
- 分辨 handle 和显示名，知道哪个进入 key。
- 从同名路径识别不同用户的 namespace。
- 区分归属用户、操作用户和作者。
- 理解定位与访问权限的关系。
这些目标导出内容深度。账号认证协议、数据库身份表等不由“详细”一词自动纳入。
构建提纲
先列已知概念和必要前提，再按理解关系组织标题。首段定义对象与职责；最早的例子建立基本模型；后续例子分别解释常见混淆；局部边界回答会影响使用的问题。
为每个拟写小节标注它回答的读者问题。只有“更多介绍”而没有问题的小节，先改提纲。每个小节至少贡献一个新的定义、区别、结果或判断条件。
选择页面职责：概念介绍强调理解；任务指南强调起点、步骤和结果；解释页强调关系与理由。没有可执行环境时，任务用法可作为逻辑说明，但不能编造安装与启动流程。
先写成稿，再检查模板
用模板组织草稿，但不要把“定义：”“规则：”“原因：”全作为正文标签。让段落自然连接，关键对比才使用表格。代码例子另按 TASK-04 处理。
入口页需要说清语言是什么、适合解决什么问题、目前文档性质、怎么开始读；不能用十几条约定替代介绍，也不能把所有细节塞进首页。
深度检查
对每个重要概念问：它和相邻概念有什么区别？读者会在哪里误解？能用什么小例子看出区别？这个例子的边界是什么？
“更多细节”应增加可判断的信息。重复“唯一、统一、自动、简单”不能增加深度。未定义的语言规则以具体缺口说明，不用新增能力填充篇幅。
验收
执行复述与定位任务。读者应能根据本页解释一个例子，并找到精确规则；新增页必须有入口、前提和后续路径。
成稿示范见EX-01。若改变章节位置，同时执行 TASK-05；若发现需要确认新语义，按 TASK-06 处理受影响部分。