浅谈技术文档的开发

如果我们留意各公司的招聘广告，特别是芯片公司的招聘，会发现一个职位：文档开发工程师。对这个职位的职责描述通常是”进行文档写作“、”完成产品规格说明等文档编写“、”开发产品说明资料“等等，那么文档开发工程师的”开发“，主要开发什么？或者说，开发的成果是什么呢？在我看来，文档开发包括两个层次的“开发”。

⑴ 初级开发：对来自技术团队的原稿进行加工，优化用词和语法，使其语言书面化、表达流畅化。
文档工程师 ”开发“ 所用的输入素材，源自技术部门的原稿。其特点是：优先保证技术内容的详实、准确。对于原稿的用词、语法并未深入考究，因此存在不符合技术文档要求的口语化表述、以及表达不够流畅的情形，如以下示例-1。

示例-1之技术原稿：
→ 在电池低压状态，为了减小静态功耗，芯片是没有手机插入检测功能的，也无法通过按键进行激活。

简评：
本例中，最为典型的口语化表述是『芯片是没有手机插入检测功能的』。事实上，芯片的这个功能是始终存在的，只不过在电池电压不足（低电压）时，“停止使用”了这个功能以降低静态功耗。当电池电压恢复后，会重新激活这个功能。因此，这里使用『禁用』一词替换原稿中的“没有”，能够准确地反应芯片在电池低电压时的实际操作，并且『禁用』这个中文用词和英文技术文档中的“disable”一词也是经典的匹配用词。如果将文档翻译为英文版，这样的用词也有助于找到正确对应的英文词汇。

示例-1之开发结果：
→ 电池低电压状态时，为了降低静态功耗，芯片禁用手机插入检测功能，也无法通过按键进行激活。

下面我们通过另外一个具体示例，进一步加深对文档初级开发要旨的理解，如下所示。

示例-2之技术原稿：
→ 芯片支持 1/2/3/4 颗 LED 电量显示，支持 188 型数码管电量显示；支持照明功能；支持按键。支持I2C接口。

简评：
本例的原稿中陈述了芯片支持的功能，但是各并列内容之间缺少衔接，读起来感觉生硬、不流畅。如果在各个短句之间加入必要的连词，可以使这个句子读起来更流畅。如以下的开发结果所示。

示例-2之开发结果：
芯片支持 1/2/3/4 颗 LED 电量显示，可以根据硬件连接智能识别LED数目，并且支持 188 型数码管的电量显示。此外，芯片还支持照明功能、按键功能、以及I2C通讯接口，进一步拓展其应用的灵活性。

通过对技术原稿的加工、开发，使得描述内容的用词专业化、语言书面化、行文流畅化，这个是文档开发的基本职责，或者说是文档开发的成果之一。

⑵ 高级开发：对内容的呈现方式做深加工，利用 ”直观、生动“ 的方式呈现内容。
我们以充电宝对手机电池『充电』的功能说明为例，剖析如何“开发”直观的呈现方式，生动地说明电池充电的工作过程。最朴素的呈现方式，是纯粹使用文字描述电池的充电过程，如下所示。

充电：
芯片集成了一个支持同步开关结构的恒流、恒压锂电池充电管理系统，可以自动匹配不同的充电电压规格。当电池电压小于3V时，采用300mA涓流充电；当电池电压大于3V，进入恒流充电，电池端最大充电电流5.0A；当电池电压接近设定的电池电压时，进入恒压充电；当电池电压接近恒压电压且电池端充电电流小于100mA时，停止充电。充电完成后，若电池电压低于4.1V后，重新开启电池充电。

简评：
电池充电的过程，由 “涓流充电—恒流充电—恒压充电—停止充电—恢复充电” 共计5个步骤组成其循环往复的完整充电过程。并且各步骤的执行是有固定的先后顺序的。如果使用带编号的分句来呈现这5个步骤，更能凸显各步骤的先后执行顺序，因为编号本身就有“顺序”的暗示含义。改善后的呈现方式，如下所示。

充电：
芯片集成了支持同步开关结构的恒流、恒压锂电池充电管理系统，可以自动匹配不同规格的充电电压。
⑴ 电池电压＜3V时，执行充电电流等于300mA的涓流充电；
⑵ 电池电压≥ 3V时，进入恒流充电，电池端最大充电电流5.0A；
⑶ 电池电压接近设定的电池电压时，进入恒压充电；
⑷ 电池电压达到恒压电压且电池端充电电流小于100mA时，停止充电；
⑸ 充电完成后，若电池电压低于4.1V后，重新开启电池充电。

如果能进一步开发出以下的充电过程示意图和上述的步骤相配合，那么就是非常优秀的文档开发成果了。

充电示意.png

为了说明文档开发、特别是高级文档开发的核心是 “内容呈现方式” 的开发，我们使用另一个简单示例做进一步的说明。

对于充电宝的应用方案，通常支持过温保护功能：『通过检测连接温敏电阻的芯片引脚电压，判断电池是否温度过高或者过低。当温度超限时，执行相应的保护操作。并且，在充电和放电过程中，设定不同的温度作为超限临界温度』。这个内容常见的呈现方式如下（其中的数据，仅作示例）：

充电状态下：
当NTC电压低于 0.35V，表示温度高于50 度，停止充电；
当NTC电压高于 0.50V，表示温度低于 0 度，停止充电；
放电状态下：
当NTC电压低于 0.25V，表示温度高于60度，停止放电；
当NTC电压高于 1.50V，表示温度低于-20 度，停止放电；

当然，这样的文字描述内容，已经说明了过温保护功能。如果进一步开发这个内容的呈现方式，可以使用以下的表格。利用表格的3列内容，可以更直观地呈现 ”NTC电压、温度、保护动作“ 三者之间的关系。

过温保护.png

结束语
文档开发工作，首先需要遵循正确的工作流程，才能开发出高品质的文档。也就是说，
1）技术团队提供正确、详实的技术内容；
2）文档团队对技术描述内容做用词和语法的优化处理、并开发合理的内容呈现方式，形成文档的初版；
3）技术团队对文档团队的初版文档做技术内容的再次查读，确认优化后的文字描述是否符合技术规格；
对于文档工作者来说，只有深入理解产品之后才可能开发出高品质的内容呈现方式。理解产品的技术规格通常是通过和技术团队的深入交流实现的（口头交流或文字交流）。当然，如果文档工作者自身具备良好的技术背景，对文档的品质是有重大支撑的。总之，技术内容正确是文档的灵魂，呈现方式直观是文档的颜值。高品质的文档，是技术团队和文档团队通力合作的成果。