最新消息:想上头条?没问题,只要你给本站投稿就行啦~

《科技文档写作实务》简评

原创 ChinaTechWriting 1184浏览 0评论

近日,笔者入手了中兴通讯学院编著的《科技文档写作实务》一书。在这之前,国内基本上没有与技术文档写作领域相关的专业中文书籍,应该说这本书还是很有意义的。本文将对此书进行一番简评,供大家参考。

从书名来看,“科技文档写作”显然是一个范畴更大的概念,并不仅仅局限于笔者所从事的技术文档写作领域(相关概念:《什么是技术文档写作?》)。实际上,这本书包含了两大方面:1)研发文档写作;2)用户文档写作。除了第四章“实战篇”用了较大篇幅讲解研发类文档(需求说明、概要设计、测试用例等)的撰写外,其他章节都是通用的知识。由于笔者仅关注技术文档写作部分,因此本文不对此书中的研发类文档相关内容作出评价。

从此书中用到的技术文档写作内容组织方式来看,明显是运用了DITA的理念,虽然作者没有明确提到这一点。DITA全称是Darwin Information Typing Architecture,中文名叫“达尔文信息类型化体系结构”,近年来在国际上的技术文档写作领域很流行,尤其是在大公司中,以DITA为基础的各种商业出版解决方案应用非常多。DITA将文档主题类型划分为概念(Concept)、任务(Task)和参考(Reference)这3种:

概念

概念主题回答“是什么”的问题,提供读者能成功操作、维护、使用一个产品或者界面所必须知道的背景信息。

任务

任务主题回答“如何做”的问题,通过Step by Step的方式描述完成一个特定任务所需的方法和步骤。

参考

参考主题用于描述产品或技术中特性结构比较一致的主题,如语法规则、消息说明及参数说明等。

DITA还有其他一些特性,感兴趣者可以自行Google一下相关的资料。中兴和华为这类国内通讯巨头应该都是采用了DITA解决方案来组织技术文档出版的。至于对待DITA的态度,笔者觉得我们也不必过度推崇,大公司采用它,自有其道理,但是中小公司未必也一定要上DITA方案。毕竟,使用开源方案的话,没有一定的技术支持是玩不转DITA的,而使用商业解决方案的话,成本是一个重要的考量因素,小公司不一定愿意在这方面花钱。

这本书的“进阶篇”写得非常好,该篇详细介绍了高质量技术文档需要满足的三要素(实用性、可读性和舒适性),运用大量的实例来帮助读者提升写作质量。例如,为了说明“从方便检索的角度来组织主题”,更高效地对信息进行分类,作者举了这么一个例子:

(修改前)

基本

查询命令
查询功能介绍
查询报告的类型
立即查询

其他

高级查询命令
查询示例
定制化报告的功能
数据转换功能

(修改后)

功能介绍

查询功能
定制化报告的功能
数据转换功能

查询操作

查询报告的类型
立即查询
查询示例

命令参考

查询命令
转换命令

对比一下,修改前的案例,写作者将内容界定为“基础”和“其他”两大分类,虽然这么分也没什么错,但是给人感觉有点牵强,逻辑上不够清晰明确。修改后的案例,对目录按照内容区别进行了分类,条理更清晰,读者更容易定位具体的内容。

用英文进行技术文档写作时,由于国人普遍接受过严谨的语法训练,因此大家都比较注意遣词用句。相比之下,由于中文是我们的母语,很多时候我们都是凭借语感来写作,没有过多留意中文语法方面的问题。最常见的问题就是,中文技术文档中的章节标题,容易出现不规范现象,如忘了用动宾结构等。这本书中也有相关的讲解,值得细细品味。

在“实战篇”的用户手册写作指导中,作者用FileZilla Client来讲解,写得非常详细,对新手来说参考意义很大。

总体来说,笔者对《科技文档写作实务》一书的评价还是较高的。刚入行的技术文档工程师可以从中学到不少东西,老手也可以看看,毕竟中兴作为大企业,总结出来的一些经验还是值得借鉴的。

说完了好话,最后也提一下建议吧。

1)建议单独出一本技术文档写作的书,因为研发文档和用户文档的差异还是挺大的,读者群也明显不一样;
2)有关Style Guide的话题一笔带过,感觉有点欠缺;
3)既然中兴用的是DITA方案,那直接亮明观点,讲解更多DITA的实际运用也未尝不可;
4)部分业内专用词汇,建议注明国际通用的英文表达,以体现专业性。举个例子,在书中看到“同源开发”一词时,笔者愣了一下才反应过来,这个指的是Single Sourcing。


原创文章,版权归作者所有,转载请注明本站以及作者名称,并保留原文链接

本文链接:http://www.chinatechwriting.com/kejiwendangxiezuoshiwu-review/


The following two tabs change content below.
ChinaTechWriting
中国技术文档写作资讯网官方账号
ChinaTechWriting

Latest posts by ChinaTechWriting (see all)

发表我的评论
取消评论

表情

Hi,您需要填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址

网友最新评论 (2)

  1. 买了一本看了,个人感觉就是讲的比较浅,新入门的可以看看
    jorgensen3年前 (2016-03-02)回复