读书笔记：科技文档写作实务

中兴通讯在持续的全球高端客户文档交付中积累了丰富的科技文档写作经验，他们把他们的经验输出成这本《科技文档写作实务》。本文是我的读书笔记。

---

- 1 -

概述篇

1.1 什么是技术文档

科学技术文档（简称科技文档）以客观严谨的语言记录科技事实、沉淀科技经验、发表科技成果和传递科技信息，是科学技术知识体系的重要组成部分。

在产品研发和制造领域，技术文档分为两类：一类指产品开发中要用到的研发文档；另一类是面向产品用户的用户文档。

 

技术文档具有以下特征：

• 针对性：技术文档要有明确的读者对象，针对不同类型和层次的读者，文档内容和深度均不相同。

• 专业性：技术文档不同于小说、散文等文学作品，其内容一定会涉及某个技术领域的专业知识，有些技术文档甚至要求读者具备一定的专业背景才能阅读。

• 功能性：技术文档的存在，一定是以解决实际问题为目的，具有帮助读者学习技术知识、正确使用产品、顺利完成任务的功能。

• 规范性：技术文档使用的语言要严谨规范，使用统一的规范术语和缩略语，遵循行业标准，套用固定的技术文档模板。

1.2 技术文档写作的国际国内状况

在国际上，技术文档写作作为一个研究领域已经得到了多年的广泛关注和迅速发展，目前已经形成了完整的理论体系，例如Darwin Information TypingArchitecture（DITA）写作理论。

反观国内，对于技术文档写作的研究和教育尚处于起步阶段。

1.3 技术文档写作的重要意义

技术文档写作的专业化水平不仅是衡量企业发展成熟度的一个指标，更在企业国际化的进程中发挥着至关重要的作用。

- 2 -

基础篇

技术文档写作流程：

 

- 3 -

进阶篇

进阶篇围绕高质量文档的实用性、可读性和舒适性三大要素，详细阐述可以通过哪些办法和手段来实现这些质量要素。

3.1 实用性

实用性是指文档有多大的用处，是否能有效地解决问题。

实用性通常包括以下内容：

• 安全第一；

• 内容准确；

• 面向任务；

• 组织合理；

• 内容完整。

3.2 可读性

可读性是指读者阅读和理解文档的方便程度。人们对阅读理解的过程应该是渐进式的，根据这个特征，可读性包含易读、易理解两层含义。

• 易读是语言层面的要求，通常表现为对词语、段落、句子以及对图、表、项目列表等的要求。

• 易理解是指在语言简洁明了、语义明确的基础上，能借助一定的编写技巧帮助读者理解文档所要表达的含义。通常的手段包括举例、定义术语、一目了然的标题、概括中心思想和“傻瓜式”操作步骤。

3.3 舒适性

文档的舒适性是指读者在使用文档和阅读内容的过程中，对文档呈现的样式效果欣然接受、感觉舒服的综合感受的程度。

文档的舒适性主要体现在以下3点：

• 文档获取便捷；

• 内容检索高效；

• 阅读感受舒适。

一个企业或者组织具备样式模板和写作规范，是保证文档舒适性的一个重要法宝。

技术文档写作黄金法则：

1. 主题明确单一；

2. 语言简洁明了；

3. 图表优于文字；

4. 例子增加理解。

- 4 -

实战篇

4.1 如何写需求说明书

需求说明书作为产品需求的载体，是由产品规划人员负责编写，用于向系统设计人员传递开发需求的文档。

内容框架：

• 一、引言

• 二、术语、定义和缩略语

• 三、综合描述

• 四、具体需求

需求说明书写作流程：

 

4.2 如何写概要设计文档

概要设计文档由系统设计人员编写，以需求说明书为依据，主要描述系统的总体实现方案，建立系统的逻辑模型，定义系统的布局、各个子模块的功能和模块间的关联，本系统与外部系统的关系等。

内容框架：

• 一、引言

• 二、术语、定义和缩略语

• 三、概述

• 四、总体设计

• 五、组件设计

• 六、接口设计

• 七、数据结构设计

• 八、容错设计

概要设计文档写作流程：

 

4.3 如何写软件模块详细设计文档

软件模块详细设计文档的作用是确定待开发软件模块的内部结构和处理逻辑，以指导后续的实现和测试。

内容框架：

• 一、引言

• 二、术语、定义和缩略语

• 三、相关文档

• 四、模块概述

• 五、设计思路

• 六、模块结构

• 七、协作流程

• 八、类设计

• 九、数据定义

• 十、函数定义

软件模块详细设计文档写作流程：

 

4.4 如何编写测试用例

测试用例是对特定产品的测试任务的描述，体现测试方案、方法、技术和策略，需要针对具体产品的功能、业务设计测试用例。

内容框架：

• 一、引言

• 二、术语、定义和缩略语

• 三、测试环境

• 四、测试用例

• 五、其他说明

• 六、参考资料

测试用例写作流程：

 

4.5 如何写使用指导文档

使用指导文档用于指导读者完成某项操作，这种操作具有明确的、有意义的目的，如指导读者完成安装过程、指导读者实现产品中某功能的操作过程。

内容框架：

• 一、引言

• 二、术语和缩略语

• 三、产品概述

• 四、功能介绍

• 五、操作指导

• 六、常见问题处理

使用指导文档写作流程：

 

4.6 如何写故障处理文档

故障处理文档通常在产品开发的后期完成，用于传递如何分析故障、解决故障的技能。

内容框架：

• 一、引言

• 二、术语、定义和缩略语

• 三、概述

• 四、故障处理指导

• 五、参考资料

故障处理文档写作流程：