如何提升科技文档写作的质量和效率

如何提升科技文档写作的质量和效率

朱文祺

上海中兴软件有限公司201203

摘要：进入新世纪以来科技技术日新月异，产品多样性、集成化、智能化程度越来越高。用户对产品的功能和性能及使用方法的需求愈发强烈。贯穿在产品全生命周期其中的是科技文档，依靠科技文档实现在不同环节的知识传递和产品价值链的连接，在企业与市场间架起桥梁。

关键词：文档；写作；架构；

引言

一般来说，好的科技文档要求明确、定义严谨、方法直观、简洁规范、善用图表、易读而无歧义。但不少企业重开发生产，轻文档写作管理，常出现文档质量及管理滞后于产品；文档写作随性且口语化以至难以理解；文档没有建立有效传递渠道；更为严重的是引起产品的法律纠纷。这些都额外增加了企业内外沟通及运营成本。

本文就如何提升科技文档写作的质量和效率进行具体阐述。

本文把科技文档写作分成8个步骤，如下所述。

1.产品理解

2.需求分析

3.架构设计

4.文档编写

5.质量控制

6.文档发布

7.文档交付

8.文档维护

1.产品理解

在科技文档写作前，首先要对所撰写产品有着较为深刻的理解和认识。在产品全流程内深度介入研发、测试、使用、售后等各环节并全程参与。

注意：不同类型文档对产品的理解各有侧重，如操作文档偏重于站在使用者角度对产品使用进行熟悉；测试文档则注重对产品问题的分析；设计文档写则需关注产品亮点、开发技术等。

2.需求分析

需求分析阶段需做三件事情，如下所述。

1.定位读者对象

在开发文档前，首先需要确定目标读者的岗位，明确文档写作内容。

在了解目标读者的知识背景后，方可确定文档的写作深度。对于小白类型的读者可能需要面面俱到。而对于有一定基础的读者往往可跳过某些知识点，直接描述读者关注的内容。

同时，也需注意不同地区读者的阅读习惯，例如在欧美国家读者习惯通过索引检索知识点；而中国读者则习惯通过目录或者顺序阅读查找知识点。

除此之外，还需注意到在现代快节奏的生活中，很多读者往往以碎片化方式进行阅读，写作时候需要注意简明扼要。

2.收集文档需求

在明确读者对象后，即可收集文档需求：

?原始需求

?特殊需求

?文档使用场景

?交付时间点

收集文档编写的原始需求，注意目标读者有何特殊需求。了解编写文档具体使用场景是什么。同时一定要明确文档交付时间点，务必在交付时间点之前完成文档编写任务。

3.套用文档模板

如果企业有通用或专项文档模板，可在编写时直接套用。这样在文档架构和编写方面，模板均可给文档编写者提供格式和内容编写方面的指导，减少编写工作量。

3.架构设计

各项准备工作做好，奠定好写作基础后，即可开展下一步步骤：文档架构。文档架构的2大原则为MECE原则和金字塔原理。

MECE原则

MECE原则全称为：

?MutuallyExclusive（相互独立）

?CollectivelyExhaustive（完全穷尽）

MECE原则的核心思想是不重叠、不遗漏。它是麦肯锡的第一个女咨询顾问巴巴拉·明托（BarbaraMinto）在金字塔原理（TheMintoPyramidPrinciple）一书中提出的一个很重要的原则。

MECE原则是把一个工作项目分解为若干个更细的工作任务的方法。

它主要有两条原则：

?完整性：说的是分解工作的过程中不要漏掉某项，要保证完整性。

?独立性：强调了每项工作之间要独立，每项工作之间不要有交叉重叠。

用两个疑问句可以进一步阐述MECE原则的思想：

?是否有重叠项？

?是否包含了所有的可能性？

金字塔原理

文档架构的一大宝典即为金字塔原理，基本架构为：从上往下顶层主题；次层子主题/论据；再次层论点；底层关键句。

金字塔的基本结构只有横向和纵向两个方向，满足MECE原则，不存在交叉重叠的架构。且在金字塔结构中，每层以一定的逻辑顺序架构内容。

概况起来，金字塔原理的基本结构特点，如下所述。

?结论先行

?以上统下

?归类分组

?逻辑递进

了解了金字塔原理的基本结构后，如何成功搭建金字塔结构呢？

总结为以下6句话：

?先重要后次要

?先总结后具体

?先框架后细节

?先结论后原因

?先结果后过程

?先论点后论据

想要建立成功的金字塔结构，还有如下4必须：

?任何级别内容都必须是其下级内容的总结（纵向）

?同层分类必须按照MECE原则组织（横向）

?同层各分组的内容必须按逻辑进行排列（横向）

?同层各分组的内容必须属于同一逻辑范畴（横向）

基于模板的文档架构

如果是基于文档模板进行开发，则文档编写工作要相对略简单，可遵循如下原则。

?目录层级：避免过深的目录层级。

?句子长度：多使用简单句；每句1个主题思想；对于复杂内容使用垂直布局，例如列表、表格等；变换句子长度，以避免阅读疲劳。

?段落：每段1个主题思想。主题思想在段落首句；控制段落长度，最多6个句子。

4.文档编写

文档编写时，总结了如下所述的4大法则：

?主题明确单一

?语言简洁明了

?图表优于文字

?例子增强理解

主题明确单一

主题明确单一分为2个核心内容：

?明确：读者能够清晰、准确、快速知道作者想表达的意思。

?单一：1个章节或段落中只写1个主题；1个句子中只写1个主题字或关键字；1个步骤中只写1个动作。

语言简洁明了

语言简洁明了分为如下2块内容：

?注重词语搭配

?英文文档熟记英文搭配，撇弃中文惯性思维。

?多使用专用词汇。

?简洁表达

?多意译少直译，减少不恰当句子结构。

?多用简单句少用复杂句，剔除重复信息。

图表优于文字

图表优于文字可用8个字进行概括：文不如表、表不如图。

?对于复杂内容，多使用垂直布局的表达方式，例如目录、表格等。

?在进行描述性的写作时，尝试通过变化句子长度和结构，以避免阅读疲劳。

例子增强理解

例子增强理解的核心思想是例子要有代表性。典型有代表性的例子，不会让读者产生理解偏差。同时也不能找以偏概全的例子。

注意例子不能代替正文。因为举例的目的是为了让读者了解正文的内容，对正文内容的补充。

5.质量控制

质量控制是整个文档开发流程中重要的环节，是保证文档质量的必须手段。质量控制环节中发现问题后要进行修改直至问题解决。

文档的质量控制主要有以下3种方式：

?文档审核，审核文档规范性

?文档测试，测试文档正确性

?文档验证，验证文档可用性

6.文档发布

文档写作完成后，下一步就是发布为正式交付的文档。文档的表现形式有多种，如PDF、HTML等，可以根据需求对文档内容进行组织和包装，发布为不同的文档呈现形式。

7.文档交付

文档完成之后还需要交付到读者手中。

交付的途径有多种。对于研发文档，由于读者是企业或项目内部人员且涉及保密，所以一般采用内部服务器共享文档的方式进行交付；对于用户文档，可采用网站交付或直接寄送的方式。

8.文档维护

文档交付给读者后并不是终点。很多时候因为功能改进需要，产品在不断更新（例如系统版本更新），对应文档也需要维护更新。另一方面文档可能会存在某些错误也需要维护修订。

文档的维护修订可能需要重新进行需求分析和架构设计，相当于重新写作而不仅是文档写作中的一个环节。

结束语

通过以上介绍，相信读者已经对科技文档的写作要点有了一定的认识，科技文档写作只有理论结合实际，在实践中完善写作能力，才能写出更适应时代的科技文档。

参考文献：

[1]BarbaraMinto（芭芭拉·明托）.金字塔原理[M].北京:民主与建设出版社,2002.

[2]BarbaraGastel（芭芭拉盖斯特尔）.科技论文写作与发表教程[M].北京:电子工业出版社,2018.

[3]马平.软件文档写作教程[M].北京:电子工业出版社,2010.