如何写好技术文章/书籍:四个指导原则

1,561 阅读10分钟

标签: 公众号文章


不知不觉专职写技术文章/书籍的时间已经有两年了,刚开始是摸着石头过河,什么东西都是尝试着来,今天再回头看我最初写的一些东西还是蛮幼稚的,希望再过两年看我今天写的这些东西也能产生这种感觉吧(那才能说明我进步了嘻嘻)。

当我们从事一门工作时,首先要界定清楚我们要达到的目的是什么。对于写技术书籍/文章的我来说,目的很简单,就是:让同学们更快、更舒适的掌握我想让他们掌握的那些知识。达到这个目的比较困难,不过在不断探索中逐渐形成了我自己的一套写作方法论,今天这篇文章就着重于我自己提出的写技术文章的四个指导原则,主要是给下边两类同学看:

  • 对于刚刚开始写作的同学们,希望大家可以少走些弯路。

  • 对于学不懂某一门专业知识的同学们,虽然我不能让大家立即把专业知识学会,但是至少可以让大家明白自己为什么学不会。

    小贴士: 我的一个观点:对于大部分工程技术问题来说,理解并掌握它们并不需要很高的智商,但是需要解释这些问题的人下一些功夫,从初学者的角度出发来解释问题。也就是说:学不会东西不怨大家,是我们的文档没写清楚~

好的,废话少说,所谓的写技术文章的四个几本原则就是指:

  • 简单
  • 简洁
  • 有趣
  • 系统

我们下边分别来看一下。

简单

计算机是一个非常精密的机器,我们可以用叹为观止来形容,简直比艺术品还艺术品。不过即使是经过成千上万科学家精心研究的这个艺术品,底层也只不过是由一堆晶体管组成的,我们作为程序员平时使用C、Java这些高级语言写出的程序实质上是在操纵这些晶体管。比方说我们用C语言敲了一行printf的代码,然后把它编译运行,最后在屏幕上把它显示出来,这样的一个简单的操作,其实是经过层层调用得到的:

  • 我们的应用程序(这里是一个C语言的程序)会调用操作系统提供的往屏幕上输出一行字的接口,称之为系统调用,不同厂商可以生产不同的操作系统,比方说UnixLinuxWindows之类的。

  • 操作系统接收到需要往屏幕上输出一行字儿的指令和内容之后,会调用相关硬件的机器指令,这些机器指令其实就是010101...这样的二进制代码。不同的厂商生产的不同机器有不同的机器指令体系,比方说x86MIPSPowerPC等等等。

  • 这些010101...二进制代码它们本身没有啥意义,针对同一个指令体系来说,不同的厂商可以针对同样的机器指令画出不同的电路图,比方说对于x86机器指令的体系,Intel公司和AMD公司可以真对同一个机器指令开发出不同的电路图,这个电路图就是所谓的微体系结构。

  • 电路图其实就是个图,它是由各个具体的逻辑组件组成的,比方说做加法需要加法器,做乘法需要乘法器,存储数据需要触发器吧啦吧啦的。

  • 而这些逻辑组件本质上是数字电路,由与、或、非以及其他的一些基本逻辑门构成的。逻辑门还是一个抽象的概念,它假设电路里只有0和1两种状态,但是实际的电路中只能靠电平(或者说电压)来代表电路的状态,而电平的变化是一个连续变化的过程,不是单纯的从0点平直接跳到1电平,所以我们把在某个区间内的电平认为是0,某个区间内的电平认为是1。

  • 模拟电路中的电平信号是连续的,它是靠底层的一些硬件来导电的,比方说继电器、真空管、晶体管啥的。

  • 继电器、真空管、晶体管这些器件是怎么导电的呢?我们只能认为这是大自然的魔力,或者说大自然的一种规则。

从这个过程可以看出来,这样子的抽象把一个极其复杂的问题分配到了不同层级去处理,就像把军队分成军、师、旅、团、营、连、排、小工兵一样,最高级别的指挥官会下达一个较为抽象的命令,比方说把某个地方给攻占掉,之后这个命令层层落实到最基层,每一层都有自己的任务,但是最具体的任务还是要给小兵去完成。

说了这么多,我们只是想说一个极其复杂的系统背后肯定是有其抽象层级的,作为解释者的我们需要把这样的抽象层级给解构出来,直到解构到足够简单让用户理解,然后再把它们串联起来形成一个大的系统。为了做到简单,我们给出一些可以落地的建议:

  • 清晰的结构划分。

    这个过程类似于思维导图,我们首先搞清楚自己要讲清楚的主题是什么,然后这个主题是由哪几个部分组成的,每个部分又能继续化为更小的哪些部分。化成的这些部分的相互依赖关系是如何,千万要记住一条硬性规定:不要用一个没有解释过的概念去解释另外一个新概念,这种情况是导致用户学不懂的首要元凶。

  • 魔鬼藏在细节里,对一个概念的充分解释

    很多同学以为写的字越少,可能意味着越精华,这纯粹是胡扯。我的经验是我们给出的细节越多,读者更容易理解,读者在越多过程中会产生很多疑惑,细节列出的越多,留给读者产生疑惑的情况就越少,这样他们的思路就更不容易被打断。

  • 把某些不适合展开讨论的概念当作黑盒对待,但是要显式的对读者声明

    我们的文章/书籍的篇幅有限,不可能把每个概念都讲述的十分清楚。这时候我们的首要思路是想办法绕过这个概念,在使出浑身解数都绕不过时,需要显式地跟读者说明这个概念我们暂时不讲,只需要知道它有一个什么样的属性就好。

    小贴士: 就我的写作经验来说,那些当前还不着急介绍的概念十有八九都能绕过。

简洁

简洁直白一点儿的翻译就是废话不要太多。

  • 我们在写作之前一定要明确自己介绍的主题是什么,然后与这个主题所有无关的东西都可以算作冗余部分,可以用一句或者两句话介绍带过。因为对于无用概念的过多介绍会让读者降低读者注意力,分散注意力的后果就是他们可能分不清那些是重点,哪些是没用的。

  • 避免概念过多出现在一个地方。

    如果你发现自己在某个不长的篇幅里连续引入了大量的概念,而且看上去密密麻麻的介绍性文字,中间也没啥段子的话,那你就要小心了,这样的篇幅容易引起读者不适,很多人会下意识的先扫一眼,发现里边有好多自己不认识的词儿,心里立马就有了抵触,这种抵触情绪会影响到他的阅读体验,从而更难真正理解你所描述的内容。所以如果你需要在某处介绍大量概念的话,这时你就需要考虑如何拆分这些概念,你可以把它们拆成不同的主题,或者在同一主题里拆分到不同的地方去描述。

  • 图表让文章立马变得简洁

    语言在图表面前是十分苍白的,真滴~

有趣

首先说一下,有趣简洁在很多地方都比较冲突,如果你想让文章更有趣,那就得适度牺牲简洁,把握好度比较重要,这个度就像厨师的火候,不可说~

  • 能用咱土语描述的就千万别扯过多的专业术语,专业术语用多了,就成了文言文,让人看多了就忘了是个啥意思。有的时候为了表述某个观点你觉得汉语不够使了,你扯点英格蕾丝也是可以的嘛。

  • 段子该用就用,甚至可以是我们刻意设计的,笑点掌握在自己手中那是种高级境界,我目前还差着远呢~

  • 注意趣味性不能喧宾夺主,沦为儿童读物。

系统

系统可以表述为一种知识的闭环,写书的时候尤其要注意,写单篇文章的时候也要稍微注意一下。

就是说我们把要讲述的那些主题划分成多个模块后,将每一块的依赖关系划分出后,先讲那些简单的,再讲那些复杂的,最后全部都联系到一块就形成了我们要讨论的主题,针对每一块,我们都要考虑清楚:

  • 我们在讲什么东西?
  • 为什么会有这个东西?
  • 这个东西有什么用?

一个概念的产生不是凭空想像出来的,它是有它存在的环境的,我们把它们诞生的情景说清楚,然后把它们和其他模块的依赖说清楚,就可以形成一个浑然天成的体系,用户们也就可以获得一个慢慢的学习成就感。

关于正确性

我们怎么没有唠叨内容的正确性呢?哈哈,这玩意儿还用强调么,多找几本参考书,多对照着源码看一下。虽然我们是人就可能犯错,但是希望可以尽量让错误少一些吧~

结语

希望我们的技术文章/书籍越来越好,曾经帮助过我宣传《MySQL是怎样运行的:从根儿上理解MySQL》的公众号「架构师之路」的博主沈剑老师对我说:“我是技术人,不是商人”,与各位共勉,尽量改变一下国内技术书籍晦涩难懂的现状,一起加油⛽️

题外话

写文章挺累的,有时候你觉得阅读挺流畅的,那其实是背后无数次修改的结果。如果你觉得不错请帮忙转发一下,万分感谢~ 这里是我的公众号「我们都是小青蛙」,里边有更多技术干货,时不时扯一下犊子,欢迎关注: