技术文章写法浅谈

写作前

自测

在写一篇文章之前,先想清楚以下几个问题:

  • 文章类型(教程型,总结型,钻研型)
  • 这篇文章是写给谁看的?有必要写吗?(分析受众)
  • 这篇文章主要讲些什么,不讲些什么(解耦知识)
  • 你真的了解这些知识吗?(知识总结)
  • 这三个问题想明白了,其实一篇文章也就呼之欲出了。

分析受众

在我们产品之前,需要先分析目标用户,写技术文章也类似,明确了目标读者,你才知道要产出一篇怎么样的文章,一切脱离了读者写出来的文章是不会获得预期的反响的。比如说招聘季,写一些面试题的分析就很吃香。

比如,你的目标是小白用户,他们可能连 Node.js 都没有安装过,你上来就让他们配个 webpack 以达到什么目的,这肯定不靠谱,你就得先告诉他们如何去安装 Node.js。

但如果你的文章面向的是更深层次的探讨和分析,为了这部分小白用户去增加篇幅大可不必,只会让那些真正的中高级开发者觉得这篇文章废话连篇,原本的价值大打折扣。

像《从入门到精通系列》这类出版的书,也是为了照顾新入门的准开发者们从零基础开始的,涵盖不了精通所需的很多东西,而像《JavaScript 忍者秘籍》这样的书又不会讲解最基础的语法内容,新手就可能一头雾水。实际上,一本书不可能面面俱到,一篇文章就更不可能了。

内容的必要性,不仅仅是指文章部分内容有没有必要,更重要的是整篇文章是不是一个伪需求。如果一个东西的官方文档十分清晰,没有任何陷阱可言,或者是市场上已经存在了对应的文章排在搜索引擎的前三名,完美解决了你想要解决的问题,那大可不必写一篇类似内容的文章,因为那并不能创造文章应有的价值。从另一个角度讲,你可以去寻找一些其他文章没有提到或者说清楚的点,去进一步深化文章的内容,创造新的价值。

解耦知识

我们有时候会遇到这样一种情况,在解释某一个问题的时候,这个问题接连产生了另一个问题,如果读者不知道前置知识,或者后续问题我也觉得值得介绍,该怎么办呢?

在刚刚我们已经讲到了首先要明确你的目标读者,比如你讲「Webpack」这个主题,在限定目标读者时,就应该限定读者有前端构架工具和工程化自动化这样的概念基础。

在比如说我们写完了一个服务,有许多问题都值得大谈特谈,可以说上三天三夜,但是如同模块的解耦一样,我们可以抽出一个个小的模块来一章一章的单独说明,对于一些明显与自己的业务有关系的名词或者代码,将它们抽象成更系统的架构中的小模块,而不是强迫读者去理解你所做的具体业务。

一个服务,写的代码是业务,做的设计是系统,但是表达出来的,应该是架构。

这种知识的解耦在一些系统级别的文章中是非常有必要的,文章同样是可以模块化的。
它能让你的文章更加独立,同时也更容易理解你在这项服务中的核心思路。

知识总结

在写文章之前,我们先要反复向自己提问:自己真的搞清楚这些知识点了吗?如果还没有,不要轻易落笔——这同时也促进自己去真正深入理解这些知识点。可能大家都会遇到相似的问题,看到一篇技术文章,苦思冥想而不得解。有时候是作者自己的思路很混乱,并且对知识的理解并不深刻,换位思考,我们在写技术文章的时候就要理清思路,保证自己对文章内容的正确理解。

为了搞清楚你想解释的问题,你会去收集一些比原来你解决时看到的多得多的资料,来力图确保自己内容的正确性,可以把这些内容保留下来,作为自己之后的「参考文献」。

如果你觉得你想明白了,不妨想想,如果你是读者,会不会有这些知识储备,能不能明白你在说些什么,这和小黄鸭调试法类似。在确保了自己能梳理清楚整个知识点之后,方可落笔。如果不明白,也可以把一些需要的知识储备放在文章的最上方并注明,方便用户进行学习。把自己设定为目标读者,以此来总结全文知识,也是一个非常重要的能力和方法。

写作时

大脑里有了整篇文章想要表达的主旨思路之后,文章其实呼之欲出,在写作时我们还应该注意一些行文细节,供参考:

行文风格

在编写文章内容的时候,不应该去追求高大上的表达方式,或者过于浮夸的表现手法,我们的目的不是参加散文比赛,应该力求文字的通达晓畅,最重要的是能够让你的读者读明白,理解你要表达的意思。

文章的层次结构

如果文章比较长,那么可以考虑在文章最前面或者在段落前给人以暗示:接下来的内容与前文内容的递进亦或者是并列关系。对于较长的文章(超过 1000 字即可考虑),太过随意的层次结构会显得全文支离破碎,不成系统,很难让人理解作者想要表达的含义,可以适当使用不同层级的标题来表达出文章的层次结构。

清晰的中英文标点

如果是中文写作,请务必用中文标点,因为那能让你的句与句之间变得更加清晰明确,请务必使用正确的标点符号来表达你的意思,慎用诸如感叹号之类的带有情感倾向的标点。

长短句结合

短句可以加快人们的阅读速度,根据某研究,短句可以加强人们的阅读兴趣,然而过多的短句会让文章变的过于琐碎。过多的长句会让人感到疲惫,适当的长句和短句的结合就可以很好的控制阅读的节奏。

段落长度适中

为什么许多人不喜欢论文和教科书,而更喜欢博文呢?因为前者的段落中信息量太大,往往一眼望去,一页一段落,一篇一世界。对于一般的技术文章而言,一段最好控制在五六行左右,不会显得文字堆砌,更能引发读者的阅读欲望。

错别字

古人可能把错别字当通假字,但对于技术文章而言,过多的错别字,尤其是错误的技术名词,比如一些技术名词的规范书写:javascriptJavaScript。可能会引起人们的反感:「不专业」的帽子就会扣过来。此外,一些错别字还会造成阅读时的停顿,可能会需要大脑额外停顿去处理这些错别字,影响了阅读体验。

谨慎的把握文章基调

技术文章不意味着十分死板和说教,你可以在自己的博文中显示出自己的幽默和风趣的语言风格,但仍然应该处于一个可控的范围,让人感受到这是一个有涵养和有趣的人,而不会认为这是一个轻浮、没有真材实料的人。

写作后

自发审核

对于大多数独立博主来说,自发审核是最后一道工序,自己过一遍,确保没有犯低级错误和误导性的错误,然后就可以轻轻一点发布了。

版权相关

在发布前,请务必注意你的文章中所有引用部分符合了原作者的规定,若为成段使用,使用之前可以先咨询原作者获得授权。要有版权意识。

无人问津怎么办

「莫愁前路无知己,天下谁人不识君」这句诗在这里也适用。文章的内容是一回事,推广又是另一回事,你的文章发布出去,事情已经成功了一大半,最起码你收获了对知识的深刻见解。如果不想费力推广,发在一些社区和专栏里,你的受众自然会「有一双善于发现的眼睛」。

上一篇:HUE简介


下一篇:我个人实现的C++之get和set方法,使用宏定义