前面我们介绍过,技术写作就是帮助普通读者了解如何使用一个复杂的产品或服务。如果某个产品的文档信息非常易于理解和使用,那么用户的信息体验自然会提升,也会有利于增加产品在市场上的受欢迎程度,甚至影响一个公司在行业内的形象,所以现在越来越多的企业都非常重视产品的技术文档开发工作。
但是,如何写技术文档才能让读者有较好的阅读体验,却是一个仁者见仁、智者见智的问题。甚至有些人认为根本不需要考虑读者的感受,把技术写好写准确就可以了,但这其实是一大误区。因为技术文档的读者大部分是普通读者,而非技术专家,所以一定要考虑如何用读者可以理解的语言,而不是你认为好的语言进行写作。
有这样一个故事广为流传:
2、这报纸要在电脑或手机上看;
3、报纸里只有家人和朋友的新闻,第 2 页是儿子的、第 3 页是妹妹的…
4、他们的新闻他们自己写;
5、其中有一页是你自己的,想写什么、想让谁看,你说了算;
6、报纸第 1 页,是全部内容的摘要。
是不是感觉非常通俗易懂?进行技术写作时,一定要时刻想着用适合读者的语言来表达。这就需要技术作者在写作过程中不断思考,这样写读者会有什么感受。如果不能让读者有一种收获的喜悦,或者阅读体验不佳,很可能写作的文档就是有问题的。
那么,到底该怎样进行技术写作呢?
其实,技术写作的过程也是一个项目管理的过程,我们可以按照以下五个步骤来进行技术文档的规划和写作:
在这个阶段,技术作者要和整个研发团队一道讨论客户需求、设计产品功能。这是为了明确产品在这个版本需要实现的功能,同时了解其中哪些功能会影响到文档信息。之后,技术作者需要做一个大致的文档信息规划和工作量计算,供团队成员参考。虽说这个阶段不涉及文档信息的实际撰写,不过,前期工作的重要性绝对不容小觑。毕竟,科学合理的规划可以令之后的工作事半功倍。
在这个阶段,技术作者开始着手撰写文档信息。可以借助一些工具来提高效率和翻译质量,比如基于 XML 和 DITA 的工具。另外,沟通也非常关键。这里尤其要提到开发人员,他们是最清楚产品功能的人,如果自己有不了解的地方,要及时有效地与他们沟通。
文档信息撰写完成后,要发给编辑和开发人员审校,这个阶段是对我们撰写的文档信息进行信息传递和技术层面的双重审校。技术层面就不用多说了,就是看我们写的文档信息是否在技术上是精确的。至于信息传递层面的审校,编辑也会遵循一套完整的写作规范进行审阅,当然啦,这套规范也是在撰写文档信息时需要遵循的。每个公司都会有自己的一套写作规范。
文档本身完成审校之后,如果没有问题,就会发给全球化部门进行翻译。之后,会将文档按所需要呈现的形式发布,例如有些要生成 PDF,有些要放在网页上。这个阶段,要确保信息最终的交付成果没有任何问题。
文档发布之后,有可能开发团队发现存在瑕疵,或是客户反映了一些问题、需要改进产品性能或是修复。这时就可能又需要我们进行技术写作,发布一些技术说明或者技术文档。有时,根据产品的发布周期也会更新整个文档。这些都属于后期的维护工作。
总之,技术写作是一个信息传递的过程,而不是简单的记录。技术写作的核心就是:让普通读者在良好的阅读体验下,看懂、学会甚至掌握文章所要传达的信息。掌握了这一点,我们就能从读者的角度出发,按照读者的思考逻辑去写,从而提高技术文档的可读性。