选择文档类型
| 读者需要 | 文档类型 | 建议顺序 |
|---|---|---|
| 第一次跑通一个示例 | 教程 | 预期结果、准备工作、分步操作、验证 |
| 完成一项具体任务 | 操作指南 | 适用场景、前置条件、步骤、检查结果 |
| 查找参数和返回值 | 参考 | 签名、参数、返回值、约束、示例 |
| 理解行为和原理 | 概念说明 | 概念定义、适用场景、运行过程、相关限制 |
一页围绕一个主要目标展开。重复出现的说明放在相应的参考页中,在正文首次使用时链接到具体章节。可参照阮一峰的中文技术文档写作规范梳理文档体系。
组织标题和段落
站内文档用 frontmatter 的 title 生成唯一的一级标题。正文从二级标题开始,按层级添加小节。操作标题用动词开头,比如“安装依赖”。参考标题直接使用对象名称,比如“返回值”。标题末尾省略标点。
每段处理一个问题,首句交代结论或动作。操作有先后时用有序列表,同类并列项用无序列表。需要按同一组字段对照多项信息时,用带列标题的表格。条目内容较长时,可以拆成小节。
安排说明的位置
在读者需要判断的地方交代限制。会影响结果的默认值写在相关选项旁边。会中断操作的条件写在对应步骤之前。把可执行的例子放在刚介绍的功能附近。
为同一个主题建立不同入口
例如,关于搜索索引,教程可让新手从一篇示例页面生成索引,操作指南可解决已有站点换输出目录的问题,参考页列出配置字段,概念页解释构建与读取之间的关系。用能反映各自用途的标题区分入口,再在读者需要查阅的词语上添加链接。