技术写作收集一些技术好文谈写作

研发老兵看技术写作

2017-07-13  本文已影响248人  怒放的中年大叔

做了十几年的IT研发工作,对用户文档这块工作一直没有太多关注。用户文档属于产品的附属部分,从项目管理角度看,用户文档往往不在项目的关键路径上,占项目预算比例低,技术风险、日程风险都很低,一旦发生问题,影响往往也不大,问题也容易得到解决。在项目管理中,往往不会过多关注用户文档。

最近一段时间,对写作产生了很大兴趣,开始关注技术写作和身边的技术写手们,通过和她们交流,开始对技术写作有了一些初步认识。

什么是技术写作?

技术写作是一个专业领域,是通过写作来进行技术传播,比如大家经常见到的产品说明书,用户操作手册,安装指南等,它为各行各业服务,比如计算机、电子、医药、机械等,形式多样,有纸质媒体,电子文档,网页,在线帮助等。

技术写作有着特定的范围,不是一个泛指的名词,很多和技术相关的写作并不属于“技术写作”行业的范畴,比如《科学美国人》里的科普文章,技术网站上的产品评测报告等。

从事技术写作的专业人员叫做技术写手,她们完成专业的技术文档。

技术写作在国外很普遍,在国内尚未引起足够的重视。比如在维基百科上,Technicalwriting, technical writer等相关条目都没有中文版本。国内从事技术写作的往往是跨国公司,技术写手们配合国内研发团队提供面向全球的英文版的技术文档,和本地化的技术文档。大部分国内公司往往对技术写作不够重视,各种用户手册和国际水平相差较大。一些优秀的国内公司,比如华为,对技术写作非常重视,对中文的技术写作发展起到推动作用。

技术写手的背景

国内专业的技术写手大部分从事英文技术文档写作,尤其以信息行业居多。专业背景主要来源于两方面,语言相关专业和技术相关专业。技术写作既需要语言、写作能力,也需要技术能力。写手们也需要对两者都抱有很大兴趣。

技术写手们走向这条职业发展道路,也往往是由兴趣驱动。技术专业背景的对于语言和写作有着浓厚的兴趣,语言专业的对于技术产生兴趣,这种跨界的兴趣又恰好被技术写手这样一个职业所满足,既能满足个人的兴趣,又能提供一个职业发展空间。重视技术写作的公司又往往是有品位的业界领先公司,能提供比较好的工作环境和企业文化。

技术写手们往往具有稳定的职业轨迹,较强的职业认同感。

技术写作的特点

技术写作的阅读对象是各种用户,主要目的是技术传播,写作风格要求客观、中性,使各类用户能够准确、快速的了解必要的产品信息。

因为目的和目标对象的不同,技术写作不像各类文案、文学作品一样要去打动人心、优美的语言。反而很多时候要反其道而行之。

简洁、准确,用词要简洁、准确,行文要简洁、准确,结构要简洁、准确,在准确传达信息的基础上,还要尽可能的节省用户时间。对于国际化的产品,目标用户可能来源于世界各地,技术写作有可能会用到简单英语,这是英语的一个子集,精选了必要的少量词汇和语法,用于基本的表达,简单英语可以大大降低非母语英语读者的阅读门槛,同时减少歧义。除此之外,还有各种写作的风格可供大家借鉴。

技术文档,需要帮助用户在合适的时候发现合适的内容,往往并不是要求用户顺序阅读的,所以往往是采用结构化的方式来组织各种信息。怎么组织,如何设计结构,信息在什么地方呈现,信息如何汇集,这些都大有学问,需要精心设计。良好的结构设计有利于用户及时发现准确的信息,也有助于文档工作者维护、修改。

管理成熟的跨国公司,往往具有完善的技术写作规范,比如爱立信公司,就详细定义了写作的语言风格,文档的结构,生成文档、查看文档的工具,文档写作、审查、验证的流程,确保了技术文档的质量和全球各地用户阅读技术文档的体验。

技术写手的成长

技术写手需要在写作和技术上协同发展,很多写手反映技术的学习和提高是非常关键的。有多种学习途径,通过翻译学习,阅读手册学习,观摩具体的操作,操作相关的产品、从做中学,向技术团队同事学习,同行之间的切磋和互相学习。

技术写手经常要面对新的产品和技术,需要不断的学习,这是挑战,也是这份工作带来的乐趣所在。一个优秀写手的成长除了自身之外,也需要环境的支持,包括技术团队的支持和同行的支持。

一个有经验的技术写手,需要有同理心,站在终端用户的角度去考虑,用户阅读文档的时候是什么场景,如何满足他的需要,如何带来更好的用户体验等等。

为了实现这些目标,满足用户需求并带来良好的用户体验,技术写手需要像设计师一样工作,她需要了解用户心理。有些技术内容很重要,但是用户有可能会忽略掉、或者遗忘,需要考虑适当的强调和合理的重复。对于复杂的产品,庞杂信息项目,各种不同级别的细节程度,如何组织结构,信息放置在什么部分,什么层次,哪些位置都需要精心。输出的文档,产生的过程如同其他技术产品、软件产品一般,都需要设计、思考、表达,满足用户体验,所不同的就是工具和产品的形式不同而已。

技术写作和研发团队的配合

技术文档也是向客户最终交付的输出物之一,文档的内容和产品的功能和操作息息相关。技术文档的交付往往也由产品经理(产品负责人)负责。由产品负责人和技术写手沟通产品的功能,技术文档需要包括的范围,比如新功能描述、操作、安装、配置等。技术写手负责完成具体的写作工作,技术文档的内容还需要专业的测试人员进行测试,用来保证文档和产品的一致性。

在写作过程中,写手需要和开发团队密切合作,了解产品的具体操作、配置等必要的细节,在敏捷开发环境下,新功能在短周期内进行快速迭代,写手需要配合迭代的节奏完成相关的文档工作。

研发团队本身也有很多研发文档需要完成,比如架构文档,设计文档,测试文档等,在研发实践中,很多技术人员具备很好的技术能力,但是缺乏必要的文档写作能力,文档质量不高,很多时候导致研发效率下降。技术写手如果能够和研发团队密切合作,快速、有效的提高研发团队的基本文档写作能力,对于提高研发效率、产品质量也是大有帮助的。

尾声

用户说明书、手册往往是随着产品一起交付的,和产品、产品的包装一样属于用户体验的一部分。乔布斯要精心设计iPod,iPhone的外包装,形状、大小、颜色,还有内包装,产品和各个配件的放置方法,甚至设计了用户如何打开包装,如何看到产品,如何把配件一一拿起的过程,这全部都是用户体验。

用户说明书也是这个体验的一部分,对于很多产品来说,用户在使用产品之前会快速的查看简要的说明书,或者说明书的某些章节,在使用过程中也有可能查阅技术文档,也可能会时时查看联机说明,这些都是用户和产品互动的一部分,也是很重要的用户体验。需要进行思考和设计。

技术写手不只是写手,她们也是设计师、思想者和产品制造者。她们交付的技术文档,也是用户体验的一部分。目前,或许只有真正优秀的产品才能真正投入精力提高技术文档的质量。希望将来能看到越来越多的优秀产品和设计精良的技术文档。

上一篇下一篇

猜你喜欢

热点阅读