跳到正文

确定读者和范围

识别读者已经具备的知识、正在解决的问题,以及页面要承担的任务。

从一件具体的事开始

写草稿前,用“读者已经有……,现在要……,完成后能看到……”确定范围。例如,读者已有一个能在本地构建的文档站,现在要生成离线搜索索引,完成后能在断网时搜到标题。这个结果同时界定了要解释的操作和需要验证的行为。

读者的起点可以来自一个重复出现的 Issue、一段常被误用的示例,或一次已发布的代码变更。用现有页面的标题和读者报告的原话确认他们正在找什么。读者说“升级后搜索空白”时,先弄清旧版本、目标版本、索引是否生成,再判断问题属于构建、迁移还是运行时。

声明必要的前置条件

列出缺失时会让操作失败的条件,例如可用的运行时版本、已有项目、访问权限或输入文件。对读者已经需要具备的技能,用简短说明和指向具体步骤的链接交代。读者需要会运行命令时,给出运行目录和使用的终端。

读者起点需要交代的信息
第一次安装工具支持的平台、安装位置、版本确认方式
在已有项目接入功能最小兼容版本、需要新增的配置和验证方式
从旧版升级受影响的旧配置、默认值差异、升级后的观察结果
遇到明确错误错误出现的位置、判断分支、恢复办法

给不同读者合适的入口

同一主题可以按文档类型提供多个入口。教程解释每一步会产生什么,配置参考给出类型和默认值,故障排查从错误现象开始。在每个页面交代完成当前任务所需的内容,接着把读者引向有实际作用的下一步。

有多个环境时,先写出读者用于选择的条件。例如,“已使用系统服务运行进程”与“在终端手动启动进程”对应两种重启方式。确认读者能从自己的环境辨认真正适用的步骤。