用途:把技术内容写成外行也能一次读懂、读完能照做的文档。核心理念是清晰优先于完整,读者决定一切(工程师要代码示例、管理者要结果、新人要背景),术语是缺陷,结构即导航,抽象解释必须配具体例子。
主要流程:
- 发现访谈(强制):在动笔前分批提问,第一批问是什么与为什么(要记录什么、为何需要、是否更新既有文档),第二批问给谁看与怎么用(主要读者、读后能做什么、文档放哪里),第三批问约束(格式模板、篇幅偏好、禁止包含的内容)。若用户提供源码、笔记或规格,先读材料,只问材料没回答的问题。
- 选择文档类型:按发现结果匹配最接近的类型,并查阅 references/document-types.md 获取模板与结构。类型包括 How-To 指南、概念解释、API 参考、SOP/运行手册、架构文档、决策记录、README、发布说明、入职文档、流程文档。不匹配时可组合,但需在开头声明主要目的。
- 起草:一句一个想法,主动语态,动作前置;术语首次出现即替换为平实语言或就地定义,缩写首次出现需展开;用编号写有顺序的步骤、用项目符号写无序列表,标题层级不跳级,对比和结构化数据用表格;每个主要章节至少一个具体示例,示例放在解释之后,使用真实感数据,代码需同时给出命令与预期输出;篇幅与目的匹配。
- 自检:检查首段是否说明是什么与为何关心、目标读者能否无障碍理解、读者能否照做、能否在10秒内通过标题定位、抽象概念是否都有例子、是否无术语、命令与链接是否仍准确、是否有会让读者卡住的缺口。
- 呈现并迭代:给出文档覆盖内容的一句话摘要、文档本身、所做取舍的说明,并询问是否符合需要,按用户确认迭代,修订时对被改章节做干净重写而非行内批注。
文档元数据:每份文档顶部应包含标题、最后更新日期、作者、受众;版本化文档(SOP、架构)另加版本号、下次评审日期、批准人。
限制:资料未提供具体收费、价格、平台支持情况与实测效果;required 命令类信息除示例中的 npm install 外未提供其他安装步骤。