如何写好一篇技术文章?
共 4359字,需浏览 9分钟
·
2021-07-07 21:35
技术文章有很多种,我们本文缩小一点范围,探讨的是,如何写好一篇讲原理的技术文章。
首先,我要直言不讳地说出我写这篇文章的目的:
你看,把一个事情说明白,其实很简单,只需要把自己的真实想法,如实地用人话的方式写出来,就可以了,甚至不需要动脑。
说人话
而一篇好的技术文章,最核心的目标就是,把这个技术点讲明白,让读者听懂。
所以这就说明了,写技术文章的核心要素,就是说人话。
要比不说人话的文章,你比不过源码注释和官方文档。
等等。
你觉得现在的官方文档真的是不说人话么?你错了,现在的官方文档一个比一个友好,图文并茂,就怕你看不懂。
这是 kafka 的官方文档,不但图文并茂,还有视频讲解,完全可以无脑按照它给出的步骤去操作。
所以,写让人看得懂的人话,应该是大家的共识了,我们就接着往下推理。
内功
要想把一篇文章写得说人话,该怎么办呢?
首先,你得真的懂,才能用人话的方式讲出来。
所以,大量的学习并且消化这个技术点,甚至把这个技术点所在的外延知识和内涵知识都搞懂,你才能说对这个知识点是真的懂了。
如果你的技术功底不够,请不要先把目标定在如何写好一篇技术文章,并且不遗余力地去探索写文章的技巧性。
你的技术水平,永远是决定你写文章的上限,就像内功一样。
而写文章的形式技巧,就像招式一样。
没有内功,招式再多也无济于事,有了内功再配合招式,就能天下第一。
而且,修炼自己的内功,永远不会浪费时间,即使这时你一篇文章都不写,也能收获知识不是么。
招式
当然,有了内功后,招式就变得重要起来了。
刚刚说了,有了内功再配合招式,就能天下第一。接下来我们就展开讲招式。
1. 层次性
我们来看一段 springboot 的源码。
public ConfigurableApplicationContext run(String... args) {
...
prepareEnvironment(listeners, applicationArguments);
configureIgnoreBeanInfo(environment);
printBanner(environment);
createApplicationContext();
prepareContext(context, environment, ...);
refreshContext(context);
afterRefresh(context, applicationArguments);
callRunners(context, applicationArguments);
...
}
我做了些简化,不过不重要,不知道你看完之后是什么感受。
如果没啥感觉,那我再放出一段代码,你看看,只是在上面的基础上加了点而已。
public ConfigurableApplicationContext run(String... args) {
...
prepareEnvironment(listeners, applicationArguments);
configureIgnoreBeanInfo(environment);
printBanner(environment);
Map<String, String> map = new HashMap<>();
if (env == null) {
for(int i = 0; i < size; i++) {
map.put(key + i, waooo);
}
}
createApplicationContext();
prepareContext(context, environment, ...);
refreshContext(context);
afterRefresh(context, applicationArguments);
callRunners(context, applicationArguments);
...
}
这样一看,上一个代码的美感就体现出来了吧?
没错,好多人写文章就会犯下面这段代码的错误,就是讲述的内容在不同层级上反复横跳,显得十分混乱。
比如,你想用一篇文章讲网络,就想解决一个疑惑,就是一个网络包是怎么一步步从一个节点,发送到另一个节点的。
那么你就一定要把握主干,将集线器、交换机、路由器中最核心的功能讲清楚,就好。
此时,将一大堆路由算法展开讲解,或者将 NAT 这种基于现有网络骨架的魔改技术拿出来喧宾夺主,我认为都是不合适的,除非你是想写一本书。
这就是写文章招式的第一个要领,就是层次性。
2. 连贯性
接下来讲第二个要领,连贯性。
写文章要前后连贯,不要有逻辑断层,而且最好是递进关系。
通过前面你写的东西,一定要非常顺畅地推出后面你要讲的东西。
当然,这里还要和刚刚说的层次性做好取舍。
还是举刚刚网络的例子,比如你讲到路由器,讲到路由表。如果你展开讲路由算法,则失去了层次性。如果你不讲路由表是怎么生成的,直接跳过去了,又失去了连续性,怎么办呢?
这里我的做法是,优先保层次性,但与此同时和读者明确说明一下,我们先假设,路由表通过一些路由算法,或者手工配置的方式,变成了这个样子,然后巴拉巴拉,再说后面的,就续接上了。
这样,就既没有失去层次性,又保证了连续性,而且还有个好处就是让读者抓大放小,先不要管具体的细节,这也是学习计算机知识的一种很好的方式。
这点就见仁见智了,有的人喜欢站在宏观层面去解释,有的人喜欢站在微观层面去解释,我觉得都无可厚非。
但不可取的是,站在宏观层面,去写一篇讲原理、追细节的微观文章。或者站在微观层面,去写一些宏观层面的抽象概念讲解。
举几个例子,你想讲 IO 模型的本质和细节,你用阻塞非阻塞同步异步这些名词,用各种烧水壶、取快递的例子,永远也讲不明白它的本质在哪里。
而这个问题,必须深入到具体函数的 API,内核态与用户态分别完成了什么事情,阻塞在微观层面的本质是什么,只有这样才能讲清楚这个问题,所以不要回避它。
除非你写文章的目标受众,或者你的写作初衷,就是让初学者头脑里先有个形象的认识,并不想深入到细节里。
![](https://filescdn.proginn.com/9269b285c2324765c5102ecc0b837548/05d5678a2b6108891cfd33fc07c3804d.webp)
总结
今天就从几个大方面说了下如何写好技术文章。
首先,保持说人话的写作风格,你就成功了一半。这个其实很容易,因为让我说特别严谨的那种官方话,我也说不出来,我相信大多数人自己写出的东西,都有说人话的特征。
其次,修炼自己的内功,这个就慢慢来吧,先尝试不惧怕那些计算机名词开始,遇到总是想不明白的问题,勇敢地打开源码,或者用二进制方式去看某些结构的内存和磁盘布局。所有的原理,归根结底落实到最底层无非就是数据结构与算法,而这些资料人人都能获得,你还怕什么呢?
最后,才到了真正写文章的时候,那就是招式。
首先保持自己文章的层次性,不要上下乱窜,写作的时候时时刻刻提醒自己主干脉络是什么,不要写着写着自 high 起来,把一个细节无限展开使得思维栈溢出了。
然后,保证思维和逻辑的连贯性,写的时候始终把自己当做一个刚刚接触这个原理的小白,看看能不能从前一句话,推断出你写的后一句话。如果不能,就细化一下,但如果发现细化之后影响了层次性,就明确说明下,我们先不管细节,假定 xxx,然后再往下写。
最后,写这种原理文章,要抓本质,不要再浮于表面,飘在空中,当然这个也取决于你的内功,只有内功到位了,才能看到事物的本质。
你看,都是相辅相成的,最终还是要功夫到家,再配合一些小招式,就可以成大作。
期待大家的大作!共勉!