如何写出好的技术文章 - 边窗

/ 0评 / 0

技术人员写文章,有两种思想上的障碍:一种,是觉得自己不会的写不出来;一种,是觉得自己会的没必要写。写作的目的,恰恰也是为解决这两种障碍。

一种是为了结构化自己的技能,帮助体系化知识和技能体系,即,最好的学习方式,是教给其他人,写作便是方法之一,比如刘润老师。视频是另一种方式,需要在保证准确的前提下,凝练自己的知识,并反复考量其中可能存在的素材或信息错误,比如李永乐老师。

一种是为了通过分享,帮助其他不熟悉、不了解的人,又或者方便其他人指出自己的不足,没有人能够把某种技术通过一篇文章解释的完美无瑕、完整无缺,因此写作分享是弥补或补充其他人文章不足或缺漏的重要方式。助人为快乐之本,知错乃人生常事。写作是和其他人分享经验和技术的最好方式之一,因此写论文依然是目前人类探索和证明前沿科学领域新成果的主要方式之一。

写作和写程序类似,都需要语法(修辞手法、标点符号),需要关键词(词语、成语),需要逻辑(上下文),需要结构(文章结构)。所以,写作的本质,就是通过自己脑海中所知的语法、关键词,通过逻辑设计和结构组合,将自己想要表达的信息,通过文章的形式传达给看文章的人。因此,往往好的技术人员,通常也有优秀的写作能力,无论是项目文档,还是技术文档。如果不知道怎么写,很可能,是对写作的语法、关键词、结构匮乏,或者,是对要写的技术内容没有足够掌握,就像陈述自己没有做过的事情,是无法详实、真实地描述的。前者,需要通过大量的阅读和写作锻炼,学习和练习写作,后者,则只能通过理论的探索、摸索和反复实践,最简单也最有效的办法是遍历学习。

技术文章写作时,常见的三种文章类型和文章结构如下:

介绍类

即向读者介绍某种技术,如编程语言、工具或技术实现,为了不落俗套,以及增强对于技术的理解,介绍类的文章的文章结构大体会分为:背景、作用、原理、区分、使用。

比如一篇介绍Lua的文章,背景说明Lua语言产生的背景,作用说明Lua相比其他语言的优势,知道为什么比知道是什么更重要,原理说明Lua的设计或语法,区分说明语法和其他类C语言的差异,使用说明具体的语法中的使用或技巧。

文章结构并非需要刻意划分段落或写作顺序,而是需要在文章中需要说明这些方面的内容。

排错类

描述某个问题或错误解决的过程,并在过程中深入某种技术。排错类文章的结构大体分为:问题描述、常规做法(以及不足)、解决过程(以及技术点、技术优势)。

比如一篇讲小米电水壶故障的文章,问题描述是电水壶无法加热或反复加热,常规做法是寻求售后解决或换一个热水壶,常规做法不足是无法一探电水壶原理及结构,解决过程是拆掉电水壶,查找相关材料,确定电水壶电路结构,重新焊接NTC传感器焊点。

排错类文章需要在文章开头描述清楚问题及现象,对于读者而言,问题描述决定了是否要继续阅读,或是否有足够吸引力继续阅读。

总结类

对于某个技术点做归纳、总结,方便发现技术共通点,以及后续类似问题的排查。总结类文章的结构简单,通常只需要技术概述、技术分类。

比如一篇总结各类定位方式的的文章,概述部分是定位的目的、作用和常用方法,分类部分是对常用方法的技术原理介绍。

总结类文章是相对容易的一种写作,需要的是针对技术点的大量检索和阅读,最后做归纳、整理即可。

写作中常见的一些问题,就像程序Bug一样,需要加以注意。

在不同的场合,文章的受众不同,需要采用不同的措辞和方式,用受众能够理解和接受的方式传递信息。向不懂中文的老外解释什么是“牛逼”,和向中国人解释什么是“牛逼”,所用的方式是完全不同的,前者,可能需要说“it's so big!”

一图胜千言,但并非每一种图片都需要。文章中图片的作用,是为了帮助更好地理解文章的意思,若文字本身已经能够完整解释,则图片便没有存在的必要,甚至还会让文章显得冗长。另一种作用,是为了做为陪衬,总结或加强文字的意思,比如漫画或meme,需要适当,过多会让阅读无法连贯。

尽可能少放图片,如果有,需要注意图片展现。写作的文章,在不同方式、不同渠道的分享过程中,会因为各种各样的问题导致图片或多媒体内容的丢失,而文字相对不容易出现这种情况,因此少放图片可以让分享更加自由,同时也是练习写作技巧的机会,这也是为什么小黄文比小黄图更难的原因。写作完毕后,需要注意查看其中图片等多媒体呈现的效果,比如图片过小、视频无法播放等等。

切题、切题、切题。有的人写文章是先写标题,再写内容,而有的人是先写内容,再起标题,目的是在成文后,通览全文方能想出一个合适的标题。所以标题需要契合文章内容,不能过大,也不能过小,但常见的错误是标题太大。比如,C程序设计语言,这个标题的文章,如果不是完整介绍C语言的书,那么就是文不对题的标题党。

标题和内容表达要直接。文笔再好,但是不直接,会造成无法事后检索,文章阅读冗长且枯燥,比如我几年前写的多篇文章,标题过度使用隐喻,文章过度使用修辞,导致事后检索内容时,根本无法从标题看出文章内容是什么。

好的文章,需要多写、多改,文章即是产品,好的产品,总会让人感到美好。

知识共享许可协议  本作品采用知识共享署名-相同方式共享 4.0 国际许可协议进行许可。

发表回复

您的电子邮箱地址不会被公开。