跳到正文

文档类型与结构

根据读者的任务选择教程、操作指南、参考或概念说明,并组织标题和段落。

选择文档类型

读者需要文档类型建议顺序
第一次跑通一个示例教程预期结果、准备工作、分步操作、验证
完成一项具体任务操作指南适用场景、前置条件、步骤、检查结果
查找参数和返回值参考签名、参数、返回值、约束、示例
理解行为和原理概念说明概念定义、适用场景、运行过程、相关限制

一页围绕一个主要目标展开。重复出现的说明放在相应的参考页中,在正文首次使用时链接到具体章节。可参照阮一峰的中文技术文档写作规范梳理文档体系。

组织标题和段落

站内文档用 frontmatter 的 title 生成唯一的一级标题。正文从二级标题开始,按层级添加小节。操作标题用动词开头,比如“安装依赖”。参考标题直接使用对象名称,比如“返回值”。标题末尾省略标点。

每段处理一个问题,首句交代结论或动作。操作有先后时用有序列表,同类并列项用无序列表。需要按同一组字段对照多项信息时,用带列标题的表格。条目内容较长时,可以拆成小节。

安排说明的位置

在读者需要判断的地方交代限制。会影响结果的默认值写在相关选项旁边。会中断操作的条件写在对应步骤之前。把可执行的例子放在刚介绍的功能附近。

为同一个主题建立不同入口

例如,关于搜索索引,教程可让新手从一篇示例页面生成索引,操作指南可解决已有站点换输出目录的问题,参考页列出配置字段,概念页解释构建与读取之间的关系。用能反映各自用途的标题区分入口,再在读者需要查阅的词语上添加链接。

需要一个短任务的步骤时,从实用配方取结构。需要选择标题层级或调整目录时,用标题和段落规则核对读者能否扫读页面。