技术写作三步走

最近几年 Peter 都在从事技术内容的生产,于是我鼓动朋友也动手开始写,朋友发现提起笔来越写越难受。其实一个事你要觉得难受,肯定就坚持不了多久了,所以 Peter 来跟你分享一下我写一篇文章的具体步骤。教是最好的学,我觉得这些步骤可以把写作的压力分散开来,让每一步都变得很轻松,让创作成为一个愉悦的学习过程。

第一步素材积累

选定一个主题之后,我会去 Google 和 YouTube 上找到所有我能找到的资料,几十篇文章和演讲,我基本三个小时就能看完,过程中笔记怎么来做呢?

我自己很少画思维导图,但是我的过程跟思维导图其实是一个道理,工具是我自己的编辑器,或者使用类似于石墨文档这样的舒服的在线编辑器。笔记是一个不断重构过程,我会用有层级关系的列表,如果你懂 html 的话其实就是写 ul 无序列表,来记录有价值的内容。一个要点下面有可能会有几个子要点,某个子要点随着我阅读和理解的深入,有可能被提升成一个父要点。 阅读开始之前我通常不限定我会写些什么的,整个文章逻辑是在整理笔记的过程中不断清晰起来的。

那什么内容会被忽略,什么内容会被添加到笔记中呢?我一直关注的是那些拍大腿时刻,用老外的话来说就是一些 aha moment 。靠,这个要是不知道肯定不能算理解这个问题啊,靠,这个我以前还真是不知道啊,靠,这个类比真是深刻。等等等等,凡是真的有含金量,同时是在我思维主线上的内容,都会被记下。而相反的,如果内容我觉得太难的,基本上默认都会被忽略,这样才保证了阅读速度。一边阅读,一边我自己的主线会越来越清楚,于是这条主线上一些必要的环节我都会写成问题记录下来,这些问题是一定要死磕下来的,也就只有在这种情况下,我会有目的的回去看之前被我忽略的那些比较难的内容。

第一步积累素材,主要技巧就是这些了,这个过程中会自然的围绕主题慢慢的形成论述主线。但是这个过程中我不会强迫自己去整理清楚行文逻辑,因为这样压力会比较大,阅读乐趣就降低了。

第二步整理论述逻辑

素材积累的够多了,就可以进入第二步,整理论述逻辑了。大思路非常简单,就是把整篇文章分成三四个部分,然后把素材填充到各个部分中。给各个部分取一个清晰的标题,每个部分有前后承接,层层递进的关系。

缺乏写作经验的人有一个特点就是想到什么说什么,觉得有价值的就说,说完了,论述又不充分,这样的文章基本别人是看不懂的。Peter 觉得写作的第一心法,就是咱们小学一年级就学过的,文章要有中心,所有的部分标题都要服务文章中心。每一部分也要有中心论点,文字要服务部分中心。每一个自然段都要言之有物,要么是金句要点,要么就是在解释论述这个金句,不发散,不炫耀。

各个部分的前后承接,层层递进也很重要。任何技术话题都是有难度的,但是任何的难度其实都是可以拆解的。比如我要解释清楚一个复杂的技术框架,就可以先在第一部分中介绍清楚框架的要解决的核心痛点和设计哲学,先抛开具体组件,让读者形成一个思维框架。接下来第二部分,我会先抛开辅助组件,专门聊这个框架的核心组件,技术术语涌上来了,但是因为数量较少,所以读者也比较容易接受,逐渐把各个组件摆放到之前形成的框架上的各个位置,好像玩一个拼图游戏。最后一部分,再去聊辅助性的组件,根据文章篇幅,内容可多可少,要勇于抛弃。

层层递进的论述逻辑,可以把概念拆解,前后有承接,有印证,读者读起来就会觉得带入感比较强。这就是我要说的三步走的第二步了,整理论述逻辑,这步下来,文章的骨架就有了。

第三步一气呵成文章

下面进入第三步,一气呵成文章。文章不厌百回改,肯定不适合作为快消品的技术写作。我自己以前写文章最头疼的事情,就是写着写着要调整文章骨架,结果发现越改越不通顺。所以进入第三步之前,务必要要把第二步工作做扎实,骨架搭建好。

写作风格要服务写作目的。技术文章不是写论文,也不是写官方文档,所以严谨不是第一目的。技术文章是个小快餐,第一目的是,管用,好懂。 所以技术文章的写作就应该像朋友聊天,自然最好。以前我自己有个误区,就是惜字如金,认为一个意思只能说一遍,任何的重复都是智商低的表现。其实根据信息论的原理,重复和冗余能够有效的提高信息传播过程中的抗噪音能力,是高效沟通的必备技巧,尤其适用于技术文章这样的一次性消费品。所以行文的时候不要有压力,想扯什么就扯几句,只要保证不跑题就行。相信我,别人读你的文章如果觉得啰嗦无聊,绝对不是因为你多啰嗦了几句,而是因为你的论点本身就没含金量。

当然,聊天我们也不希望浪费朋友的时间的,所以有些明显的标志,让朋友能迅速抓住要点,决定是否要读文章的某些内容,也是一篇贴心的技术文章应该努力做到的。所以我希望我读到的文章第一自然段要把文章的核心内容说清楚,至少要把想要解决的问题说清啊老大,别让我文章读到一半了才发现文章根本不是我需要的。另外,文章的最后一部分应该给出一个清楚的结论,有些文章明显是在讨论一个问题的解决方案,但是读到最后我都找不到答案在哪里。另外,进入某个部分道理也一样。第一句提问题,说出中心,最后一个自然段也总结一下,个别的时候,的确也没啥好总结的,这个时候也稍微说它一两句,起码给读者一个明确的信号,让大家知道我们这部分可结束啦,要进入下一部分啦,要睡着的同学该醒醒了。人都是喜欢逻辑美感的物种,形式上的清晰,泾渭分明也是很讨读者喜欢的。

总之第三步,一气呵成写文章,就是把第一步积累的金句素材,变成自己的话得过程。这其实有个前提要求,就是第一部分要记录素材的时候就是记录真正有用要点,而不记录别人的论述逻辑,只是用自己的话几个字描述清要点,而不是大段拷贝人家精彩的论述。倒不是说涉嫌抄袭,因为我们肯定会注明出处。主要是如果记录人家的论述逻辑,几十篇文章,语言风格不一样,最后也不太可能糅合成一篇通顺的文章。

总结

好,今天这篇 《技术写作三步走》,主要内容就是这些了,最后来总结一下。创作是个艰苦的过程,那么如何让整个过程变得轻松一点呢,就是要分步骤来做。第一步,我只负责去搜罗素材,记录成有大致的层级结构的笔记,主要精力用来阅读和体会,不去苛求逻辑,于是就是很轻松。第二步,主要去整理逻辑,整理出各个部分的标题,然后把素材按照内容分开,这一步只负责逻辑,并且处理的都是一些非常简略的要点,没有阅读的工作量,所以也轻松。第三步,要写文章了,就是把之前的要点一条条的用自己的语言论述清楚,就跟自然聊天一样,不用考虑逻辑,因为第二步工作中去保证,不用考虑文章含金量,因为这是第一步去保证的,所以只要保证自然,跟说话一样就行。好,最后复述一遍,第一步积累素材,第二步整理逻辑,第三步一气呵成。实际操作中还有很多细节,不过这里不展开。