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