文档组织逻辑

文档写作应该围绕一个核心主题组织信息，遵循先总后分的法则，先阐明核心主题，然后将支撑或解释该主题的所有信息按照一定的逻辑顺序排列。

先总后分的法则，同样适用于单独章、节的逻辑阐述。

阐述逻辑

阐述核心主题时，可以根据内容要求将信息按某种逻辑顺序排列，这样会使文档条理清楚，便于读者阅读和理解。

时间（步骤）顺序

达到目的依次采取的行动顺序或按照事物发展的先后顺序介绍某个事物。

时间顺序常用于任务主题的写作，比如说故障处理、操作任务。

结构（空间）顺序

按照事物空间存在方式，或从外到内，或从上到下，或从整体到局部描述某个事物。

结构顺序常用于结构、原理等主题的写作，如描述某个设备的组成，就需按结构顺序逐个描述各个组件。

程度（重要性）顺序

按事物重要性的不同来排列。

程度顺序的运用通常用于强调某些重要信息，通过重要性排序将这些信息依次排列。如故障处理类文档，对于多个可能的故障原因描述，可以按照故障发生概率由高到低的顺序依次排列。

基于读者考虑

在规划文档组织的时候，要站在读者的角度考虑，而不是一惯的针对设备或产品功能进行文档组织。

下面的示例是一个 FTP 软件的说明书。依据产品功能编写的章节为：

1.1 服务器管理
1.2 传输管理
1.3 使用地址窗口

基于读者角度编写的章节：

1. 上传与下载
    1.1 连接网络服务器
    1.2 上传与下载文件
2. 查询地址

文档组织逻辑模板

模板是将一个事物的结构规律予以固定化、标准化的成果，它体现的是结构形式的标准化。

软件手册

软件手册建议采用下面的结构。

  • 简介（Introduction）：[必备] 提供对产品和文档本身的总体的、扼要的说明

  • 快速上手（Getting Started）：[可选] 如何最快速地使用产品

  • 入门篇（Basics）：[必备] 又称”使用篇“，提供初级的使用教程

    • 环境准备（Prerequisite）：[必备] 软件使用需要满足的前置条件

    • 安装（Installation）：[可选] 软件的安装方法

    • 设置（Configuration）：[必备] 软件的设置

  • 进阶篇（Advanced)：[可选] 又称”开发篇“，提供中高级的开发教程

  • API（Reference）：[可选] 软件 API 的逐一介绍

  • FAQ：[可选] 常见问题解答

  • 附录（Appendix）：[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容

    • Glossary：[可选] 名词解释

    • Recipes：[可选] 最佳实践

    • Troubleshooting：[可选] 故障处理

    • ChangeLog：[可选] 版本说明

    • Feedback：[可选] 反馈方式

分章节模板

依照总分原则，章节标题下，介绍完章节主题后，建议将本章的文件插入到下面。

第二章 文档写作
####################################

文档章节主题综述。

章节目录
------------------------------------
2.1  文档写作四法则
    2.1.1. 主题明确单一
    2.1.2. 语言简洁明了
    2.1.3. 图表优于文字
    2.1.4. 例子增强理解

2.2  文档组织逻辑
    2.2.1. 阐述逻辑
    2.2.2. 基于读者考虑
    2.2.3. 文档组织逻辑模板

2.3  段落的组织逻辑
    2.3.1. 分类与归纳组合
    2.3.2. 精简语句
    2.3.3. 标题

2.4  句子写作方法
    2.4.1. 避免使用长句
    2.4.2. 语义明确
    2.4.3. 其它