技术文章是怎样炼成的

「你那么能写,怎么不上天啊。」

于是乎,我们就来谈谈,怎么写一篇技术文章。

「你那么能,怎么没火啊。」——本文仅作交流,不火怪我咯。

Chapter 1. 写作前

提问

有些人可能会纠结,我的语文水平打小就不好,我还能写作吗?——出小说恐怕没什么指望,但技术文章却完全可以,技术文章考察的更多的是一个人的思维逻辑和表达能力。

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

  1. 这篇文章是写给谁看的?有必要写吗?(分析受众)
  2. 这篇文章主要讲些什么,不讲些什么(解耦知识)
  3. 你真的了解这些知识吗?(知识总结)

这三个问题想明白了,其实一篇文章也就呼之欲出,如果没有看懂,没关系,我们一个个来看。

分析受众

在我们做一个产品之前,往往需要先分析我们的目标用户,写作也是一样,有了目标用户,你才知道要产出一篇怎么样的文章,一切脱离了用户造出来的东西都是耍流氓。

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

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

实际上,一篇文章不可能面面俱到,所谓《从入门到精通系列》,即使是书,都是为了照顾新入门的准开发者们从零基础开始的,涵盖不了精通所需的很多东西。

当然,有必要写不仅仅是指一些内容有没有必要,更重要的是整篇文章是不是一个伪需求,如果一个东西的官方文档十分清晰,没有任何陷阱可言,或者是市场上已经存在了对应的文章排在搜索引擎的前三名,完美解决了你想要解决的问题,那大可不必写这样一篇文章,因为那并不能创造文章应有的价值。

解耦知识

在讲一个问题的时候,我们有时候会遇到,这个问题接连产生了的是另一个问题,万一读者不知道前置知识,或者后续问题我也觉得值得介绍,怎么办呢?

在「分析受众」一节中,我们已经讲到了要明白你的目标用户,比如你讲「生产者消费者」这个操作系统的模型,在限定目标用户时,就应该限定好,读者是否有操作系统基础,是否有多线程的概念等等。

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

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

这种知识的解耦在一些系统级别的文章中是非常有必要的,它能让你的文章更加独立——试想,如果有人需要看五万字全文才能弄懂一个他想知道的模块上的问题,还是通过一篇 5000 字比较独立的文章来解决更好?

知识总结

在写文章之前,我们先要反复向自己提问:自己真的搞清楚这些知识点了吗?如果还没有,不要轻易落笔——可能大家都会有相同的遭遇,至少是在初学阶段,看到一篇名为《新手指南》的文章,苦思冥想而不得解。别担心,有时候是作者自己都没有搞明白。

在确定了「文章写什么」之后,我们就该把自己的知识总结成团了,不应该去追求高大上的表达方式,或者过于浮夸的表现手法,应该力求能够让你的受众读明白,完全理解你要表达什么。

在这一阶段,为了搞清楚你想表达的问题,你可能会去收集一些比原来你解决时看到的多得多的资料,来力图确保自己思路的正确性,不妨把这些内容保留下来,作为自己的「参考文献」。

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

如果你是初次进行这样的训练,不妨给自己列个提纲,写下这几个问题的答案。

Chapter 2. 写作时

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

文章的层次结构

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

清晰的中英文标点

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

长短句结合

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

段落长度适中

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

错别字

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

谨慎的把握文章基调

你可以在自己的博文中显示出自己的语言风格,但仍然应该出于一个可控的范围,让人感受到这是一个有趣的人,而不反感,认为这是一个轻浮的人。

Chapter 3. 写作后

自发审核

对于大多数没有编辑的独立博主,自发审核是最后一道工序,自己读一遍,确保没有犯之前所提的错误,然后就可以偷着乐,轻轻一点发布了。

版权相关

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

无人问津怎么办

「莫道前路无知己,天下谁人不识君」,内容是一回事,推广又是另一回事,你的文章出去了,事情其实成功了一大半了,剩下的事情,如果不想费力推广,那自有你的受众用户会「有一双善于发现的眼睛」。不必担心,在写完全篇之后,相信你一定有了更多的收获。

发布于 2017-05-03

文章被以下专栏收录

    只看代码的话,上 https://github.com/ElemeFe 。这一群人,关心的不是「如何写前端」而是「如何很好地运行一个 ( web ) APP」;这一群人,会在监控屏上加上弹幕,会让实习生自主招聘,会设计、编写、监控整个 APP 的生命周期;这一群人,玩的时候... 更卖力,就像从来没来过那般卖力,卖力地热爱生活。所以这些创作大多基于 ❤️