如何撰写原创技术文章

作为一个技术从业者,一直觉得技术写作非常重要,一方面它能帮助你搞清楚很多成体系的知识,另外一方面也能提升个人以及团队的影响力。不能忽略影响力建设,因为影响力对内对外都是放大器。

但是很多人一提到技术写作就发怵,不知道写什么,怎么写,那今天我就把积攒的干货技巧整理出来,一起学习交流。

本文将从如下五个部分来聊聊技术写作:

如何设计一篇技术文章的逻辑框架技术文章如何写得通俗易懂技术文章写作有哪些技巧日常如何做好知识整理与沉淀技术写作的要素有哪些

如何设计一篇技术文章的逻辑框架

首先,我们来看下如何设计一篇文章的逻辑框架。一般我在写一篇文章之前,我会先想好我想要表达的是什么,然后为了据此设计文章的框架结构。所以动笔之前我一定会先把文章的目录写好。

如何撰写原创技术文章
如何设计一篇技术文章的逻辑框架

如上图所示,总体来说我最常用的是“起承转合”的结构,因为这个结构会比较系统,对于系统讲清楚一件事情非常有帮助。

起承转合结构

一篇文章非常关键的就是开篇的部分,因为这部分内容是第一时间和读者建立连接的,读者会不会往下读往往开篇起到了决定性作用。

第一种引出的套路是抛问题。我们看下面这个例子:
如何撰写原创技术文章

在这一篇文章的导读部分,连问了三个问题,层层递进,环环相扣,引入入胜。不得不佩服作者善于提问,连题目索性就是一个问题。获得11万多阅读,这些问题的吸引功不可没。

第二种引出的套路是讲故事。我们看下面的例子:
如何撰写原创技术文章

作者在开篇,就讲了一个故事,引用电影《墨攻》里的桥段,把程序员比作革离,把代码仓库比作梁城,革离收好梁城就如同程序员守好代码仓库,进而引出要介绍的工具 ESlint,与文章标题《ESLint - 守住优雅的护城河》呼应上。

第三种引出的套路是介绍价值。就比如本篇文章一开始就会交代要解决什么问题,通过阅读这篇文章能有哪些收获。此举能精准得锁定读者,让需要的人有兴趣读下去。

承的部分是文章的核心,是最占用文章篇幅的一部分。它需要讲清楚两个问题:

是什么怎么做 这里的具体技巧可参考后面的“如何写得通俗易懂”等章节,这里只介绍逻辑结构

转的部分更多的是解决方案的延伸、题外话、扩展阅读等等,起到锦上填花的作用。

合的部分很好理解了,就是总结、回顾、留作业(动手小练习等)以及留一些悬念抛一些后续篇幅的引子等等。

并列结构

这种结构行文最简单,适合罗列知识点,因为简单明了也深受读者喜欢。如下一个例子所示:

如何撰写原创技术文章

全篇就是一一把28个JavaScript技巧娓娓道来。

当然还有很多其他组织形式,譬如 总-分-总、黄金三点法、对比法、递进式等等

技术文章如何写得通俗易懂

把技术文章写得很难一点都不难,难得是如何把技术文章写得简单! 所以这个部分我们一起来探讨一下:

如何撰写原创技术文章
技术文章如何写得通俗易懂

换位思考

先从一个故事说起。美国的一位老太太想知道什么是 Facebook,在互联网高速发展的今天,很多老年人跟不上数字化的进程,可想而知向一位老太太介绍明白 Fackbook 有多难。然而 Ahmad Takatkah 是这样解释的:

Facebook 是一份报纸;这报纸要在电脑或手机上看;报纸里只有家人和朋友的新闻,第 2 页是儿子的、第 3 页是妹妹的…他们的新闻他们自己写;其中有一页是你自己的,想写什么、想让谁看,你说了算;报纸第 1 页,是全部内容的摘要。
如何撰写原创技术文章
换位思考

换位思考的道理我们都懂,但真的有做到吗?使用对方的语言,切换到对方的频道,不光是在技术写作上,在工作以及生活的方方面面都非常受用。

善用比喻

善用比喻也是把技术文章写得通俗易懂的不二法门,通过把一个很复杂的事情与一个大家都懂的道理建立连接,让读者恍然大悟、茅塞顿开。一起来看几个例子:

《Tree-Shaking性能优化实践 - 原理篇》中,作者为了讲清楚 Tree-Shaking ,在一开篇就使用了如下的动画:

如何撰写原创技术文章
Tree-Shaking

形象得解释了 Tree-Shaking 的本意,而前端中的 tree-shaking 可以理解为通过工具“摇”我们的JS文件,将其中用不到的代码“摇”掉,是一个性能优化的范畴。读者一下就懂了,再来看一个例子:

《Babel:把 ES6 送上天的通天塔》中,作者为了讲清楚 Babel 的组成,把它和燃油发动机联系在一起,把 Babel 组成中的各个部分对比为发动机的各个零部件,明确又生动。

如何撰写原创技术文章
Babel

一图胜千言

在描述一件事情上,有一个铁律叫:字不如表、表不如图、图不如动画,通过一个例子来感受一下。我们以疫情期间感染人数的动态变化为例

使用文字表示如下

3.11 意大利 10149 韩国 7755 法国 1774 德国 1296 美国 696

3.12 意大利 12293 韩国 7861 法国 2233 德国 1547 美国 966

3.13 意大利 14230 韩国 7942 法国 2663 德国 2102 美国 1172

3.14 意大利 17618 韩国 8084 法国 3627 德国 3050 美国 1671

3.15 意大利 20924 韩国 8157 法国 4414 德国 3746 美国 1678

3.16 意大利 24687 韩国 8235 法国 5365 德国 4821 美国 1678

使用表格表示如下
如何撰写原创技术文章
使用图表表示如下
如何撰写原创技术文章
使用动画表示如下:
如何撰写原创技术文章

实际应用

上面我们介绍了通过换位思考、善用比喻、一图胜千言等技巧让技术写作变得更加通俗易懂,接下来看几个实际应用这些技巧的例子。

《Micro Frontends》文章中,作者非常匠心的把一个 web 应用使用如下动画的形式,拆成讲述微前端的各个部分,非常巧妙。感兴趣的可以点击链接去看一下。
如何撰写原创技术文章
《CommonJS:不是前端却革命了前端》文章中,作者制作了很多如下类似的图片,形象地描述了 CommonJS 模块的导出原理。
如何撰写原创技术文章
《图解 Promise 实现原理(二)—— Promise 链式调用》文章中,作者能把 Promise 链式调用的流程使用动画绘制出来,也足以彰显其用心。
如何撰写原创技术文章

技术文章写作有哪些技巧

上面讲了很多道理,知道了动画和图的重要性,那到底该怎么画图,怎么制作动画呢?接下就一起来看看技术文章写作有哪些技巧。

如何撰写原创技术文章
技术文章写作有哪些技巧

起一个好标题

标题是一篇文章最先触达用户的内容,它的好与不好,非常影响读者继续阅读内容的兴趣。从后台访问统计数据也不难看出,一个好的标题会带来更多的流量,这也就是为什么标题党能够成为标题党的原因,这里并不是鼓励大家做标题党,不能舍本逐末。

起一个好标题可以从以下四个方面(包括但不限于)考虑:

真实可信营造冲突感引发共鸣制造悬念

《CommonJS:不是前端却革命了前端》的标题中,“不是前端却革命了前端”就是营造冲突感很典型的例子。

做一个好的开场

一个好的故事会更容易引人入胜,在开场时简明扼要地交代文章的价值,都会带来更高的完整阅读率

多画几张好图

google 支持搜索透明背景图片。这简直就是素材神器。
如何撰写原创技术文章
分享一个在线设计的神器:稿定。它就是一个在线的PS,偶尔用一下非常方便,还有很多海报的模板,可以快速生成和设计海报。
如何撰写原创技术文章
画时间线相关的图time.graphics。特别适合绘制重大事件的时间图谱。特别好看,也特别好用。
如何撰写原创技术文章
动画绘制的神器:花火数图在线数据短视频工具,好看的图表形态各异,制作的工具简单如一。
如何撰写原创技术文章

日常如何做好知识整理与沉淀

俗话说,巧妇难为无米之炊,所以日常的积累对于输出是非常重要的,接下来,就聊聊日常如何做好知识整理与沉淀。

如何撰写原创技术文章

分享几个方面吧:

多读多看

一个成年人,或者说一个成熟的成年人,理想的状态应该是“眼里充满故事,鬓尘却丝毫未染”。那故事其实就是人生阅历,就是读来的看来的。

作为一个科技行业的从业者,我每周都会看《科技爱好者周刊》,它是阮一峰老师2018年发起的,每周五上午发布,用于分享过去一周值得分享的事情。有很多新鲜的文摘、科技动态、工具等,每周还会讨论一个话题。

如何撰写原创技术文章

当然还有很多信息输入的渠道,如果大家有推荐也可以随时分享给我

多做分享

我是一个喜欢分享的人,因为我觉得每做一次分享都是将某一项知识系统整理的过程,它会驱使你把事情研究透,真正分享做完后,就会发现收获满满。

如何撰写原创技术文章

工具的使用

兵欲善其事,必先利其器。分享一个我经常用的沉淀知识的工具:Diigo。

如何撰写原创技术文章

信息爆炸之后,遗留了一地的碎片化信息,如何管理碎片化的信息,就成为每一个学习者面临的问题。

你可以通过 Diigo 解决以下需求:

收藏并整理书签 标注网页重要信息并永久存档网页副本 收藏并整理图片 归纳总结已收集内容 和别人基于某个主题互相分享所收集信息

Diigo 还提供了浏览器插件和移动端应用,可以很方便多端使用
如何撰写原创技术文章

技术写作的要素有哪些

技术写作的要素,也无外乎就是知识、技能和态度

如何撰写原创技术文章

知识和技能的部分已经分别在日常如何做好知识整理与沉淀技术文章写作有哪些技巧中介绍了。

现在我主要来介绍一下态度层面的一些想法:

1. 要用分享的精神

2. 克服心魔

大多数人的迟迟不肯下笔写的原因,是觉得自己写得差,不敢写,怕发出去被别人嘲笑。其实我们只需要把知识与经验、经历、业务做连接,表达自己的思考与想法就好。

3. 善待读者

写文章的目的是帮助别人,而不是炫耀自己有多牛,所以写作中以及之后的回复评论中,谦虚和与人为善的态度是值得提倡的。

最后,希望这篇文章能够帮助到你,开始技术文章的创作!

原创文章,作者:afeng135,如若转载,请注明出处:https://www.c2xe.com/215553.html