查看原文
其他

写好技术原创文章的一点建议

郑吉敏 Qunar技术沙龙 2023-04-08

作者介绍



郑吉敏



2019年8月入职去哪儿旅行,机票目的地事业群技术总监、技术委员会委员、业务架构 SIG 负责人,负责酒店报价中心团队、业务架构组。

2020 年金项奖评选中主导的“对内 DDD 对外 API 驱动的酒店报价业务重塑”项目获得了 CEO 特别奖。2021 年获得技术品牌最佳贡献奖,曾在 QCon、Top100、CSDI、SACC、MPD 等大会做过技术分享。


一、背景

之前,自己曾经在公司的技术公众号“Qunar技术沙龙”发表过一些文章,记录了自己主导的一些核心技术项目,并且在季度评选中均获得了发表文章所在季度的“原创之星”:

在发表这些文章之前,自己也没如此正式的写技术原创文章,但是伴随着这些文章的准备和发表,获得了很多正向反馈,自己也在日常总结、书面表达等多方面实际提升了很多。因此写这篇文章介绍了一下自己写技术原创文章的一些经验和心得,希望能起到一定的指导的作用。

本篇文章正文主要分三块,分别是“价值:如何看待这件事?”“突破:如何写起来?”“输出:一些注意点&技巧”,读者可以根据自己需求选择跳读或者只选择自己关注的章节阅读。

二、价值:如何看待这件事?

1、提升个人影响力

一篇实用的技术原创文章,可以为自己带来大量的读者,可以从侧面去表现个人包含技术在内的综合能力,大幅提升个人的影响力。持续认真的去准备及发表高质量的文章,影响力会不断的得到提升。

刚入职公司时,自己就是通过发表连载的关于稳定性治理的文章,快速提升自己在公司内外部的影响力,效果很明显。

2、内容留存,方便传播

一篇认真完成的技术文章,可以将一件事情完整的记录下来,既能方便日后回顾,也方便传播给其他人。经常,我们会在某些事情过后很久,某一个场合或某个时候,想起这个事情,这时候如果能有这样一篇当时记录的文章,它留存的价值就会被突然放大。在完成文章过程中,还可以帮助我们去做些查缺补漏,比如某个细节不清楚、某个数据感觉有问题、某个知识点了解的不够深入等等,相比汇报和分享,写文章会让我们把想表达的内容掌握的更全面更具体,这些对自己相当于是增量价值。

2020 年自己曾带领团队完成了一次成功的 DDD 落地实践,然后我花了几个月时间去总结并将自己了解的过程和经验写成文章。之后陆续做了一些 DDD 落地经验分享,每次分享后都有不少同学私下沟通一些细节,这时候直接拿出自己之前发表过的文章,既方便回顾又方便传播。

3、提升个人总结能力

总结是对工作实施结果的总鉴定和总结论,是对以往工作实践的一种理性认识,是做好各项工作的重要环节。通过总结可全面地了解以往的工作情况,明确工作方向,提高工作效益。总结还是认识世界的重要手段,是由感性认识上升到理性认识的必经之路。可以明确,总结能力对每个人都非常重要。

通常要搞定一篇技术文章,需要我们做很多总结。经常写技术文章,可以让我们养成日常做总结的习惯,个人的总结能力可以随着日常的不断总结而不断提升。即使不写技术文章,提升个人总结能力也十分重要,而写技术文章是提升个人总结能力非常有效的一个途径。

三、突破:如何写起来?

1、从0到1 :从没写过到写过

通常迈出第一步是最难的,什么事情第一次做都会很打怵,即使有再多人告诉你不难、你不要去想xx,心里的那种陌生感依旧会依然伴着你,这个阶段的核心是突破自己内心的障碍

这时的障碍主要来自两方面:

  • 个人内容方面:担心自己的内容总结的不全或者高度不够;

  • 他人观点方面:担心比自己厉害的人笑话自己写的不好。

明确一下,有这两方面担心很正常,当然,这两方面的担心其实也都好解决。分别说一下:

  • 个人内容问题:我们写的文章都有面向的群体,面向初级、中级、高级、TL还是总监,内容高度是有很大区别的,写文章前明确好定位和面向群体就可以了,不同岗位、不同职级的人本身对文章的需求差别巨大,并不是高度够高就好。举个例子,新出一门语言,能快速写一篇文章把 API 讲解清楚,可能是当时价值最大的,而如果这个语言向 Java 这样流行之后,再去写一篇讲解 API 的可能读者就要少很多。同时,我们写完文章,通常会拿出来给身边一些人审核(非个人公众号一般都有审核要求),如果内容真的有些问题,会有很多人告诉你该如何修改,因此能最终发表出来内容问题都基本不会有明显的问题。

  • 他人观点问题:一定有很多比我们厉害的人,那么这些人会带着什么心态去看这些文章呢?首先可以明确不是带着批判的心态,其次他们可能也希望通过文章去补充自己,看看是否有新观念、新想法的出现。即使不符合他们的胃口,比如讲的内容自己可能做得更好,他们会很快关闭去看其他的,而不是继续浪费时间。反之,如果发现有你可以提升的,可能还会联系你,告诉你他们的一些想法,这样自己就赚到了。当然,还有一种可能,他们可能并不会打开。总之,这方面也没有什么可顾虑的。

2、从1到N:从不愿意写到主动写

迈出第一步之后,接下来这个阶段的核心是持续积累总结输出

先说下积累和总结,这个分重点记录和临时记录:

  • 重点记录:高质量的文章,需要不断的积累素材和总结经验,最后通过文字表达出来。正如巧妇难为无米之炊,即使有特别多的有价值的事情可以拿出来写,但是没有数据支撑、没有成果评估、没有完整的方案等详细的素材,是很难下笔的,脑海里有的也是某某事情做的很不错,只了解个大概。当然,记录这些不单单就只是记录,而是让自己能清楚知道手里都有什么“牌”可以使用,这样才能从更高的维度去构思如何使用这些素材。不光是写文章,对外分享、向上汇报、晋升答辩的内容都顺手准备了。

  • 随笔记录:建议平时多记录些随笔,随时记录一下自己的想法和idea,一些特定场景产生出的想法很容易忘,需要及时记录才不会昙花一现,这些也是非常好的素材来源,这些对于工作也会非常有帮助。

有了素材,可能有些人还担心个人文笔问题,写技术文章和写情感类作文还是有很大差别的,技术文章对于文笔要求其实没那么高。我们接下来重点说一下输出技术文章的一些注意点和技巧。

四、输出:一些注意点&技巧

1、内容是王道

(1)重视完整性

我们以常见的介绍一个事情或项目的文章来举例说明,通常这类文章要讲解清楚:背景问题解决方案落地过程项目成果总结。少了其中任何一项,大家读完就会感觉缺少些内容,比如:

  • 缺少了背景,问题可能就不是问题了,背景基本能框住文章核心内容的方向,并引出对应的问题。当然,有时背景和问题是一起出来的,比如单独的解决一个线上bug。

  • 没有背景和问题,就没法去说解决方案和落地过程了,解决方案也可能不切合实际。

  • 技术文章里解决方案非常重要,通常都是文章重点,也是读者能从中获得营养最多的地方。落地过程相比解决方案,有时会弱一些。

  • 项目成果需要回归到问题和过程,并需要从解决方案和过程里拿到数据来说成果,而如果没有成果,这件事情就没法定义做的好还是不好。

  • 如果没有总结,整篇文章会显得平淡很多,通常会选择在文章最后进行升华,给出一些实用的方法论、一些经验总结等。

  • ...

(2)重视连贯性和内在逻辑

前面介绍了完整性,他们构成了整篇文章的核心模块,接下来要关注的是让这些核心模块连贯起来,并且内在逻辑要能紧密关联、互相印证。比如:

  • 解决方案要能在背景约束下解决问题,且能真正落地。

  • 总结内容要能明确解决问题的根本点。

  • 总结是基于有效的解决方案或落地过程提炼出来的,当然也可以是失败的经验。

  • ...

(3)通过结构化方式开展

关注了完整性和连贯性之后,接下来核心就是码字了,将这些都实际体现在文字里。在码字过程中,强烈建议通过结构化的方式进行设计和落地。具体来说,先确定大标题,再确定大标题下面的小标题,最后丰富细节。一定要避免想到哪写到哪,而要提前做好设计。

我们以这篇文章的形成来举个例子,首先我先列出最核心的模块:(这一部分补充过程中,可以很容易看出整体的完整性)

  • 背景

  • 价值:如何看待这件事?

  • 突破:如何写起来?

  • 输出:一些注意点&技巧

  • 写在最后

大模块属于一级提纲,接下来是补充二级提纲,单独以【输出:一些注意点&技巧】为例,我首先把他主要分成两大块:内容和美观,即现在看到的“内容是王道”和“美观不可少”,然后经过一些思考后,我又补充了下面几项:(这一部分补充过程中,就可以把连贯性及内在逻辑都想清楚了)

  • 重视完整性

  • 重视连贯性和内在逻辑

  • 通过结构化方式开展

  • 能突出重点

  • 善于使用提升高度的词汇

  • 给出明确的结论、可复制的方法论

二级提纲完成后,可以按需考虑是否还需要在个别节点上增加三级提纲。如果没有三级提纲,就可以考虑丰富每一级标题的内容了。每一级的提纲不需要一定想的特别清楚,这个的核心是快速拉出框架,辅助自己去设计好全篇的脉络,方便后续阅读,同时也方便补充具体内容。

实际补充每一级提纲时,尽量满足 MECE 原则。MECE 原则(Mutually Exclusive Collectively Exhaustive),意思是“相互独立,完全穷尽”,是麦肯锡咨询顾问芭芭拉·明托在《金字塔原理》中提出的一个分类的思考工具。在思考问题的过程中,我们需要分解问题,每一个层次的问题之间没有重复、交叉、关联,意味着“相互独立”,每一个层次都不能有遗漏,意味着“完全穷尽”。

(4)能突出重点

通常,我们需要在行文前想好文章期望最终能让读者获得什么,比如呈现什么样的观点、什么样的方法论、传达什么思想等。在实际完成文章内容输出时,我们需要去考虑重点突出哪里,然后去思考如何突出这些重点,这决定了我们使用多少笔墨去完成某些部分,以及使用什么形式去呈现这些部分的内容。同时,需要重点突出的内容也可以通过文字强调相关数字表格画图不同排版特殊字体等形式刻意突显。

总结一下,每篇文章要有自己的灵魂,要有重点的去突出你想传达的内容或思想。

(5)善于使用提升高度的词汇

核心词汇的使用,对于文章提升高度很有帮助,有时关键句子里一个升华的词汇可能就会有完全不一样的效果。

网上有很多关于这类词汇的整理,分享一下我之前收藏的一份:





大家也可以根据需要去搜索更多类似的词汇。切记,一定要日常多看多复习,这样写文章或分享时,才更容易随手拈来,做到融会贯通。

(6)给出明确的结论、可复制的方法论

很多读者在读文章前是带着期待的,有时是希望了解他人的立场,有时是希望学习一些方法论,等等,总之大家读文章都会多少有一定的目的性。

为了能让读者更容易的获取到TA希望从文章里获得的,那么给出一些明确的结论和我们总结的一些方法论是最直截了当的(方法论注意要尽可能容易被复制使用),其他内容很多都属于为最终结论和方法论提供支撑。明确这些,可以更容易组织文章的结构和内容,明确哪里需要讲清楚、哪里需要简单提一下就行。

2、美观不可少

技术文章对美观要求的其实并不高,前面内容方面的问题做好之后,其实已经核心基本已经完成的差不多了。但是,“看着舒服”会让读者更容易读下去,“看着难受”则很可能逼走读者。在追求内容的同时,还要关注一下整体的视觉美感。

注意了前面内容那部分的几项,可以保证一些基础的“内容模块化段落标准化”要求,结构会很清晰,这里简单补充一些排版时可以关注的细节:

  • 字体与字号:不同平台的通常都有默认的字体和字号,如果没有特别的设计,不建议去使用个性的字体,比较安全的字体可以考虑:微软雅黑、黑体。同时需要关注,标题的字号要逐级变小,正文的字号最小,正文通常保证统一字体和字号。如果是想做些特别强调,正文也可以考虑使用不同的字体、字号、颜色等来呈现,常见的斜体、加粗、下划线等也可以常用,可以考虑。

  • 文字颜色:通常文字颜色使用黑色或灰色居多,这些颜色的不同程度(比如深灰、浅灰)可以引入来做些不同场景的区分。如果文字引入多种颜色,通常不建议超过3种颜色。

  • 配图:明确一点,不要随意使用网上的图片,要注意版权问题,如果需要引用,需要注明好来源。配图一定要清晰,全文的配图风格建议保持一致。尽量去掉一些无用的信息,对于敏感信息不建议使用模糊的方式,建议画图时注明或者直接去掉。同时配图要注意有解读,别让读者自己去解读。这里推荐几款流行的画图工具,draw.io、processon、EdrawMax。如果自己需要画图但是感觉自己画不好,前期可以从网上或别人画的图里找一些设计灵感,图画多后,很自然就有自己的想法了。

  • 表格:展示表格时,建议第一行标题加粗,大部分时候都可以考虑设置成居中。表格的宽度建议都手动调一下,关注一下每行是不是简单调宽就可以让内容都正常展示,也避免某些行内容少但留有空白过多的情形。

  • 代码:代码截图时请注意尽量不要有浪线,截取的代码最好调整下变量名称,看到变量就知道含义。另外,不建议直接对 IDEA 等编程工具直接截图,推荐一个网址  https://carbon.now.sh/, 可以很容易的为你的代码创建漂亮的图片。

  • 标点:通常英文使用半角,中⽂使用全角,注意即可。

  • 留白:很多同学有随手敲换行的习惯,文章里不建议刻意增加换行,除非某些场景需要,比如一些配图和上下文之间,建议使用常规标题自带的留白。有时候,多余的空行很难看。

  • 其他:做好必要的检查,格式对齐、错别字检查、大小写统一、单位统一等。

3、功夫在日常

  • 多读书&阅读他人文章:“读书破万卷,下笔如有神”,多读、精读、细读,自己写作时自然会得心应手一些,这里就不展开讲了。

  • 多收藏好文、做笔记:日常读到好的文章,不管是内容好,还是构思好,都可以收藏起来,一些文章或书也可以单独做下笔记,实际写作时这些素材会非常有用。

  • 多画图、做总结:平时可以基于项目或系统画些图做些总结,这样既可以给自己提供很多素材和思路,也能提升自己的码字水平,提升自己的综合能力。

五、写在最后

“实践出真知”,听的再懂、想的再好,都不如实际行动起来,实际写起来才知道自己具体哪里需要加强,才会有自己独到的理解和收获。真正努力过后,相信每个人都可以有“无他,惟手熟尔”的感觉。


最后的最后

当下疫情严重,基本上每个人都或多或少受影响,这时候可以静下心来去思考一下自己需要提升些什么能力。疫情终究会过去的,愿一切美好如初~




您可能也对以下帖子感兴趣

文章有问题?点此查看未经处理的缓存