Skip to main content

7.1 文档工程简介

技术写作者在实际工作中,除了负责生产高质量内容外,还必须与其他职能的人员合作, 共同规划文档结构、形式、内容、目标等,并参与内容的传播、监测、评估等,因此 需要以工程学的视角来对待技术写作。

技术文本的若干考虑

无论是写作还是阅读,人们都倾向于采用”线性“的方式。我们习惯按一定的逻辑进行叙事, 也习惯逐页阅读书籍。

非线性

然而,在技术文档的语境下,阅读的目的常常是了解某个小的概念或者解决某个特定问题。 对读者而言,最重要的也许是如何在最短的时间内定位到自己需要的内容。此时,文档不必 以线性方式呈现,但必须易于检索。

结构化

所谓结构化,是指通过机器可读的标记对文本内容进行属性标注。标准的结构化的文档易于 在不同软件应用中生成、读取、互通、转换。结构化的文本,对文字本身提供了丰富的“元数据”, 便于基于规则的软件处理。

复用性

同一款软件,有多个历史版本,每个版本也许又针对不同操作系统发行相应版本。即使如此, 软件的文档中必定会有重复的内容和板块,如某项功能的介绍等。模块化的内容有利于管理 文档版本、提高文档效率、降低翻译成本。