从读者的任务出发
为页面选定一个主要读者和一个目标。写前先确认读者处在哪个环境、已经完成哪些操作、读完后能判断或完成什么。比如,安装指南的读者需要知道支持的运行环境、安装命令和验证方法。
页面开头交代读者将获得的结果。把影响操作的版本、权限和环境要求放在相关步骤之前。用文档类型与结构为任务选定合适的组织方式。
给出可以核对的结果
操作完成后,告诉读者在哪里看到成功反馈。命令有输出时,给出要核对的字段或一小段代表性输出。配置发生变化时,说明何时生效以及如何确认生效。
对容易遇到的失败,写清可观察到的现象、适用的原因和恢复步骤。常见的细节用行内链接指向能解决问题的章节。
交代步骤背后的选择
读者有时需要从两个合理做法中选一个。介绍构建输出位置时,可以先说明默认目录与可自定义的条件,再用相同示例展示两者分别会生成什么。读者能够根据现有部署位置决定是否需要改配置。
能通过文档解决的重复问题,可以从已存在的安装、参考或排错页补充说明。先用读者和范围识别问题,再在文档维护流程中记录可验证的结果。