当前位置: 首页 > 资讯 > > 内容页

微信工程师关于如何写好一篇技术文章的小Tips

发布时间:2023-03-29 04:21:08 来源:腾讯云

导语

在学习和工作过程中,作为工程师的大家都会试着写一些技术文章,或用于沉淀总结,或用于分享经验,或用于传播知识。最近几年笔者在工作之余也会写一些技术文章,也经常会思考“如何写好一篇技术文章”这个问题。但看网络上虽然好的技术文章文章很多,但探讨“如何写好技术文章”的文章比较少,本文试着就这个话题谈一下自己的一点浅见。笔者才疏学浅,目的是抛砖引玉,希望和大家一起探讨学习。

一、什么是技术文章

谈到写技术文章,首先要定义什么是技术文章。


(资料图)

这里指的技术文章仅仅指分享技术的博客类文章。也就是《腾讯技术工程》上常见的那种类型。技术文章内容主要反映技术领域独特的知识,主要体现浓缩后的成果与研究。

技术文章有哪些类型的呢?姑且可以分为大众科普型、深度技术型、方案创新型、项目总结型等几种类型。

技术文章相对普通的文章,由于专业性强、原理抽象、主题枯燥等原因,导致很多同学都觉得写好一篇技术文章不是一件容易的事。本文尝试去浅谈有哪些方法可以帮助我们写好一篇技术文章。

二、为什么要写技术文章

为什么要写技术文章?写技术文章对于我们收益在哪里呢?

分享和传播知识

技术文章的首要作用是传播知识,相信很多同学写技术的首要目的也是为了把自己所获取到知识分享出来,如果大家都愿意积极分享知识,整个团队和公司就会形成一种技术沉淀积累的氛围,这是一种无形的资产,当我们需要搜索知识的时候也会变得更简单。

沉淀总结项目经验

正如《关于技术能力的思考和总结》一文中提到的“不管是编码类的技术基础学习成长,还是相对抽象的问题解决,还是技术领导力成长。只要是成长,只要能够抓住这两个关键就一定能够成功。” 这两个关键就是反思和总结。“通过总结和反思是能够利用上时间的复利,通过这两样心法就能够使得自己成为一个能够不断丰富完善自己的人,达到这样的状态必定能够成为技术强人。”

要做到常态化的总结与反思,最简单的技巧就是写文章,通过文字的整理可以让自己的思考更加成熟,想得更加成熟以后自然而然对外就能够讲得更加清楚,能够对外讲清楚就能够更好分享交流,分享交流之后又能够反过头来去校正自己的想法和做法是不是正确。写文章的本质是一种“以写代想,以想促讲,以讲验真”的技巧。

提升个人和团队技术影响力

将技术文章公开发表,除了是自己思考沉淀总结的过程,也是一种很好的提升个人和团队技术影响力的手段。

正如《研发怎么做需求更舒服,有成长》一文中所说的。”沉淀总结是个人成长、提升组织和团队能力的关键,项目上线后可以通过内外部分享、公众号和内网论坛来扩大业务技术团队个人影响力......还可以总结问题放入知识库反哺到主动需求,进一步沉淀为工具能力,平台能力。当你开始不满足仅仅完成任务,而是思考如何更有匠心的做事时,自然成长也不会辜负你。“

三、如何写好一篇技术文章

接下来谈谈我认为写好一篇技术文章的一些方法。这些方法部分来自我看过的一些前人的经验分享,部分来自自身实践体会。首先需要表明一点,如果你的目的是写一篇热文,那么方法有很多(例如使用一些吸睛的标题和一些运营手段等)。本文并非着眼于这些“术”的方面,而尽量多谈谈“道”。如果给你的感觉是本文还是“术”偏多,那绝非我的本意,而是个人水平所限。

1.确定你的读者是谁

写一篇文章首先要确认你的读者(受众)是谁。是写给同组同事看呢?还是写给领导看呢?亦或是是写给所有对文章内容可能产生兴趣的人看呢?确定受众将会影响你文章的整个方向和风格。

比如我以前写的一篇文章的截图,大家可以感受一下。

这毫无疑问是一篇只适合组内同学看的文章,发布之后的效果肯定不会很好。这就属于不好的实践。因为这种组内信息备忘共享更适合在技术wiki文档中记录。如果想要扩大技术的受众面,需要尽量摈弃一些有限定上下文的信息,而要多提供一些通用的技术方案和思想。只有这样,这篇文章的受众面才能最大化。

《金字塔原理》中的TOPS原则的第一条就是Target to our audiences。也就是要从受众的需求点、关注点出发,只有站在对方的角度来阐述问题才能达到有效沟通的目的。而一般的读者关心的是“是什么、为什么、怎么办”三个核心问题。

那么,如何验证是否做到了满足读者需求呢。一个有用的方法是发布文章之前最后找一个没有相关背景的同学来阅读以下,检验一下效果。

2.功夫在平时

很多时候,当项目做完之后,临时想要写一篇文章,总是会感觉捉襟见肘。这是很正常的,因为项目周期往往较长,谁也不可能记得中间涉及到的每个细节。尤其是一些重要的技术问题的思考过程脉络,更是很容易被遗忘的。

一个比较推荐的方法是,平时养成习惯把一些思考过程用文档的形式记录下来。不用太过细致,一开始也可能会比较混乱,重在记录清楚所有涉及到的重点内容,并且要不断维护和整理更新(很重要,因为有时不更新的文档还不如没有文档)。对于一个项目来说,这一点尤为重要,因为如果不记录的话,随着时间的累计,你一定会忘记当时思考的很多细节,也会忘记一些决策的过程。但如果有记录在的话,即使过去一段时间,相信你仍然可以很快就可以自己串起来,这不仅对项目后沉淀技术文章有很大帮助,对晋级答辩的材料准备也是一样有很大裨益的。也就是所谓的“碎片化记录,结构化整理”。

这就要求我们平时要注重思辨总结。有人说世界上的人分为两种,一种是“思辨者“,而另一种是”吃瓜群众”。对于平时遇到的技术问题多问一个为什么是一个很好的习惯。这种技术方案有没有经过深入调研?我们的方案是否是业界的最佳实践?它的本质可以抽象为一个什么技术问题?是否可以应用于其他场景?

最后,一个小tips。项目设计文档需要认真写,因为它是以后写文章很好的题材来源。

3.如何确定文章主题

首先主题要自己感兴趣,其次也尽量要让读者也感兴趣。所以,文章的名称和简介,都是很重要的,好的主题,能够起到先声夺人的效果。

主题应该是全文的中心思想,表明作者的写作动机和构思立意。对于技术文章来说,标题最好要包含核心技术要点。

确定主题的第一种思路,争取主题能够立意新颖,避免雷同。比如《元宇宙、区块链、NFT是什么?腾讯为什么不能错过?》就属于这种类型的文章。

第二种思路,如果主题能贴近生活,那将是非常吸引人的。《王珞丹和白百合傻傻分不清楚?“相似脸”识别帮你治好“脸盲症”!》就属于这种类型的文章。

对于业界已成熟的话题,则争取全面梳理后争取把本质抽象出来。可以从多个角度和视角展开,重新审视技术的价值点。比如

《支付山河图》 卷一——交易篇》、《浏览器原理之从输入一个网址开始》、《为什么选择b+树作为存储引擎索引结构》都属于这种类型。

4.普通和常见的项目/领域亦可写,关键是找对切入点

一个典型的情况是,很多同学都会抱怨所做的是很平常的项目,没啥“亮点”,更没有任何值得写文章的地方,即使写了也会类似流水账一般。而我认为,大部分项目/领域都会有值得分享的地方,只是我们作为熟悉这个项目/领域的人,看法并不与大众一样,会刻意忽略一些技术上的亮点和难点,把所有思考过程都视为理所当然。其实究其原因,还是“只缘身在此山中”而已。比如:我写的《如何实现一个分布式定时器》 、《【万字长文】论如何构建一个资金账户系统》这两篇文章都是大家开发过程中非常常见的组件和系统,也并不涉及太多高难度的技术话题。但是发布之后,发现其实大家对这些话题还是很感兴趣的。

关于发掘技术上的亮点和难点,就需要训练一种透过现象看本质的能力(这与答辩的思路有些类似)。比如:《【万字长文】论如何构建一个资金账户系统》这篇文章看似讲了很多点,但其实都是围绕资金安全和可用性这两个核心议题在展开的。如果不能抽象出这两个点,那行文就会缺乏核心思想了。

退一步说,即使深挖一番之后,你还是觉得所做的和所学的没有任何东西可以作为“亮点”。那么好好表达清楚自己的思考过程和解决方案(最重要的是结构化,后面会讲到),给其他涉及相关领域的同事以参考作用,或者扩大技术视野,那也是极好的。

5.如何确定文章的结构

文章的结构(框架),可以理解为先写什么,后写什么,怎么开头,怎么结尾。通常写文章之前首先确定的是标题,其次就需要确定结构。结构可以通过文章的目录体现出来。我写任何一篇文章之前,都会先确定文章的目录,再往对应的章节中填充内容(并不一定按顺序)。一篇文章有目录的好处是很明显的,首先可以让读者很快就对整个文章的脉络比较清楚,其次也方便读者直接跳到自己感兴趣的章节进行阅读。问题是,应该怎么确定文章的结构呢?接下来推荐几大利器。

金字塔原理

其核心思想是:任何事情都可归纳出一个中心论点,中心论点可由三至七个论据支持,这些论据本身也可是个分论点,被三至七个论据支持,如此延伸状如金字塔。

金字塔原理的要点可以概括为:

结论先行。一次表达只支持一个思想,最好能够出现在开头。以上统下。任何一个层次的要点都必须是它下一个层次要点的总结概括,直到最后一个层级的内容是客观事实或数据为止。归纳分组。 就是每一组要点必须要属于同一个范畴。逻辑递进。每个要点都需要按照一定的逻辑顺序进行排列。

那么对于写文章来说,我们可以这么做:

观点先行:在导语和开篇中就亮出观点,吸引读者往下看。先有提纲:先列目录,再写内容。承上启下:每个段落之间想想怎么做合适的过渡和转折。结尾升华:在文章末尾最好总结全文,拓展思考。

这里有一个小建议,对于读者可能不熟悉的领域,可以在第一节中介绍一些基础概念和背景知识。目的是对齐大家的认知。方便后续章节的内容展开。在文章结尾可以尝试总结一下整篇文章的核心要点,起到加深印象的效果。

结构化思维

任何一篇文章都是结构化思维的产物。很多人觉得写东西太难,其实症结不在于对文字的把握,而恰恰是对缺乏对思维结构的把握。所有文章,必然要有“中心思想”,这就是结构化思维中的“确立目标”;为了表述这个“中心思想”,必然要分段陈述,各个段落有各自的“段落大意”,来支持“中心思想”,这个就是结构化思维中的“资源分析”;提纲出来以后,分段展开陈述形成文字,就是结构化思维中的“制订计划”。大家写文章写着写着,要不写不下去了,要不就是跑题了,其实在遇到的障碍正是在“结构化思维”训练中的不足。

结构化思维是以事物的结构为思考对象,来引导思维、表达和解决问题的一种思考方法。简单来说就是顺着事物的结构和脉络,从整体思考到局部,借助一些框架来思考,将碎片信息进行系统处理。具体操作上,结构化思维要求我们在思考分析解决问题时,以一定的范式、流程顺序进行,首先以假设为先导,对问题进行正确的界定,假设并罗列问题构成的要素,其次对要素进行合理分类,排除非关键分类,对重点分类进行分析,寻找对策,制订行动计划。

结构化思维的本质是信息熵——把知识的有序度最大化

以下是结构化思维的一些要点,可以发现与金字塔原理有某些重叠的部分。

自上而下。分析的过程通常是数据->事实->观点这样的顺序,而表达的过程则相反,先摆出观点。层次清晰。把相关议题在一个章节内说清楚,分清楚议题的层次。结构简单。表达的结构不宜太过复杂。一个简单的训练方法,叫“重要的事情说三点”。也就是列出与议题相关的三个议题。重点突出。不要试图传递过多信息,要把最想传递的信息突出出来。

如何锻炼结构化思维,推荐以下的步骤。

第1步,头脑风暴,将所有想法穷举;

第2步,将穷举出来的所有想法,分类归纳;

第3步,基于分类,提炼标题或结构;

第4步,做一些补充。

最后,要善用工具:思考时养成画思维导图的习惯。

MECE

MECE,是“Mutually Exclusive , Collectively Exhaustive” 英文首字母的缩写。中文的意思是“相互独立,完全穷尽”,它是很重要的结构分类原则。要素之间既相互独立、完全穷尽,让结构划分更加逻辑清晰。它是自上而下方法论的利刃,也是思辩者日常修炼的最为关键的科目。在写文章方面,当我们手里有很多信息不知道如何归纳整理时,可以使用MECE原则对其进行归类整理,同时还可以扩展思路,发散思维。

MECE原则有五种分类法。

二分法。 这个分类方式在日常生活中比较常见,其实就是把信息分成A和非A两个部分。过程法。也就是按照事情发展的时间、流程、程序,对信息进行逐一的分类。要素法。其实都是把一个整体分成不同的构成部分。可以是从上到下,从外到内,从整体到局部。 这种分类方法是用于说明事物的各个方面特征的。公式法。可以按照公式设计的要素去分类,只要公式成立,那这样的分类就符合MECE原则。矩阵法。比如把你的工作分成以重要紧急、重要不紧急、不重要但紧急、不重要也不紧急。然后可以把它们填到4个象限当中去,这种分类方式就叫做矩阵法。

奥卡姆剃刀法则

前面讲的都是如何“做加法”,再谈谈“做减法”。奥卡姆剃刀原理又被称为“简约之法则”,它的提出者说过这样一句话“切勿浪费较多的东西,去做用较少的东西,同样可以做好的事情。”奥卡姆剃刀定律认为保持事物的简单化是对付复杂与烦琐的事情的最有效的方式。它的理论被概括起来就是一句话:“如无必要,勿增实体”

在写文章方面,我们同样应该秉持这样一种理念,应当追求文章结构的简洁性,不应当试图在文章传递过于杂乱庞杂的信息,对于不能服务于文章中心思想的内容应该果断摒弃掉。因为这会给读者平添理解成本,而无助于中心思想的表达。

这一点大家应该都有切身体会,如果看到一篇文章,其目录结构过于复杂,或段落信息量过大,可能第一时间就有点想放弃了。 这里的建议是:

结构简单原则。按照金字塔原理确定的结构,应该是以中心思想为核心展开的,整个结构给人的感觉是“内聚”和简洁的。文字简省原则。尽量使用较短的语言和篇幅来描述一个问题。通俗原则。尽量少写生僻的文字和晦涩的内容,使用平易近人的语言,追求文章的通俗性。

6.一图胜千言

人类对于信息的接受方式决定着图片比文字更易于被接受。所谓“文不如数,数不如表,表不如图”。写文章中好的实践往往会使用大量的图片来辅助表达自己的意思。全部是文字甚至代码的文章,通常会天然地使人产生抗拒感。

下面是在另外一篇文章中看到的一个例子。

又例如,试想一下如果要表达下面这个技术场景,用文字表达的话需要多少字?但是如果用图片,只需要一张图,相信大家就一目了然了。

Excalidraw、ProcessOn、Draw.io等都是我使用过的比较好的画图软件。P.S.还有一个使用的比较多的软件是PPT,用它画图有时也能产生很好的效果。

7.文章内容,有干货才是王道

说一千道一万,决定一篇文章质量的最重要的因素还是:有干货,言之有物。

前面提到了系统设计文档,但其实技术文章与设计文档的内容是有本质差别的。比如设计文档中会有大量的UML图、接口设计、存储设计甚至伪代码,这些都不太适宜用于技术文章中。文章中更应该更着眼于更高的抽象层次,阐述好其中涉及到的技术要点为要。

这就要求我们深入思考,力求剖析问题的本质。授人以鱼不如授人以渔,同样的,授人以“术”不如授人以“道”,这样可以推广到类似的场景,上升到方法论的层次。

尽量在自己所熟知的专业领域写作,文章要体现自己的专业性,包括主题、核心思路、表达方式、流程、数据呈现都需要体现专业性。

能尽量在深度和广度上进行拓展,而不是只写问题本身,直到已经到达自己的知识盲区为止。这样一来,可以体现作者对于该领域知识掌握的全面程度,可以提升文章的level。

加入一些基于自己实践的理解,而不是纯翻译。能大大提高你的文章的价值,毕竟对于互联网科技来说,获取原始知识的最好途径仍然是阅读英文资料。

8.如何给文章润色

如果一篇文章主题、架构、内容都很好,但语言晦涩,甚至语言不通,那给人印象肯定是是会大打折扣的。力求能加入一些与大家息息相关的、接地气的例子,或者打一个生动的比喻,无疑可以大大降低大家阅读的门槛。

另外一个问题,若全篇各个章节内容都不错,但感觉不同章节之间衔接不够紧密,有“跳跃感”,也是可以优化的。可以适当增加一些前后衔接的过渡语句,使文章更连贯。

其次,注意排版,好的排版会让人阅读地更舒服,毕竟信息密度太大或者太小都是不合适的。写完后可以多预览一下最终效果,看排版是否让人读起来舒服,这也是吸引人看下去的重要因素。

关于排版有一些建议:

利用不同级别的标题划分文章结构,但最好不要超过3层。每个章节的长度适中,不宜太长或太短。句子也不宜太长,可以多使用标点分隔。写完后通读一遍,避免错别字。

总而言之,发表之前可以多读几遍,多“迭代”几个版本,反复打磨自己的文章。

9.最后,多阅读

如果有可能的话,尽量养成多读书的习惯(不仅限于技术文章)。好的文章和书籍,可以学习到很多好的行文习惯,对写好技术文章很有帮助。

比如说技术文章这块,除了各种博客和论坛之外,推荐阅读《腾讯技术工程》公众号上面发表的文章。

四、常见的几个误区

有几个固化的思维误区,特此指出,希望对大家有帮助。

1.所有的主题都适合通过写文章来表达

知识的沉淀和分享并不一样要通过写技术文章来传达,有的更适合通过技术文档(wiki)记录,而有的更适合通过PPT来表达。

2.阅读量和收藏量等于文章质量

阅读量和收藏量这两者最多只是正相关。比如有的文章标题吸睛,或者话题自带流量,又或是受众面广,阅读量自然比较高。而另外一些因为太过专业导致受众面小的文章可能阅读量不佳,但其实是“沧海遗珠”也很有可能。因此一般的社区(比如《腾讯技术工程》)都会有小编人工推荐的功能,可以避免这类文章被埋没。

3.写技术文章和写论文方式一样

很多同学学生时代都写过学术论文。但忽略了其实技术文章的写作和论文有所不同。首先论文行文非常正式,技术文章相对更为通俗大众,因此可以使用较为接地气的语言,还可以加入具有表现力的图片(甚至表情包)。论文需要追求学术上的绝对严谨性,而技术文章重在分享,不一定要做到面面俱到,滴水不漏(当然也要做到基本的技术严谨性)。

总结

总而言之,有好的主题、好的内容、好的形式,决定了一篇文章不会差。

最后,想起了我的某位领导的一句话,个人觉得很受启发,“把复杂的东西讲简单,把简单的东西讲深刻,都是比较难的事情”。

与大家共勉。

参考文章

《专业成长,你可能需要这篇结构化思维》

《结构化思维-项目经理的法宝》

《程序员写好技术文章的几点小技巧》

《关于技术能力的思考和总结》

《研发怎么做需求更舒服,有成长》

《如何训练自己的结构化思维》

推荐阅读