本文字数:3536字
预计阅读时间:6分钟
背景
最近团队有同学提议,想探讨如何才能写出一篇优秀的技术文章。所以尽管水平实在有限,还是按照自己的经验和理解写下了这篇文章,亚历山大之余,也很高兴和大家分享一下自己对技术写作的一些思考。
希望本文可以抛砖引玉,大家从中可以有所思考和收获,就能达到本文的目的了。那么,写好一篇技术文章对我们有什么用呢?
我觉得有三点:
第一点,可以更好地分享传播技术方案,让读者认同赞赏你的文章;
第二点,通过文字表达提升个人的表达能力,在做技术分享和演讲时提升效果及魅力;
第三点,通过整理技术文章,主动对技术深入思考剖析,提升个人的技术广度和深度能力。
那么,接下来我重点分享下我实践中的写作流程。
写作流程
写作流程,大体上可以分为:写作前的准备工作、写作中的注意事项和技巧以及写作后的提升工作。
通过对这三个阶段的打磨,相信你就可以写出一篇“令人满意”的技术文章。
写作前
所谓万事开头难,所以写作前的充分准备工作,可以帮助你快速进入写作状态,准确明晰写作内容。让我们通过以下手段,告别写作开始时的“提笔皱眉”,体验一把“下笔如有神”。
确定立意标题
我认为立意和标题应该是先确定清楚的,要非常明确地知道自己要写什么内容,这个“什么”其实并没有那么简单确认,可以参考以下罗列的确认要素:
内容传达的目的是什么?
内容关键字是什么?
内容触达的范围是什么?
内容的重点是什么?
最后,通过对立意的分析思考,形成一个立意明确的标题。不要小看这个标题,这个标题是文章的“门面”,有时候甚至会让读者使用“一票否决权”。所以,标题也应该首先明确下来,在写作中不断围绕立意的标题进行,这样即不会产生跑题的情况,也对内容进行了充分强化。技术文章的标题,其实不用起得那么“八卦”来吸引读者,简单直接即可。可以参考以下罗列的标题要素:
紧扣内容立意
简短清晰
确认目标读者
确认目标读者是非常重要的,尤其文章需要在一些特殊场合中进行发布和使用。是分享技术到社区?还是给领导汇报技术方案?还是具体下发开发执行方案?不同的场景,写作的侧重点和用语都需要做相应的调整。至于如何调整,这个需要对不同的环境进行判断,并不能一概而论,可以参考不同场景下要考虑的写作要素:
文章中的称谓
读者最关心的是哪部分?过程?结果?还是数据?
是否需要为读者提供某些补充资料?
形成树形提纲
在确认立意和目标读者之后,我们就可以开始“下笔”了,但是我建议不要急于写文章的主体部分,而应该先形成纸面的“树形提纲”。当然,如果写作前脑子里的“布局”就已经非常清晰,也可以省略纸面工作。其实,我们写文章,尤其是比较长的文章,是应该有目录索引的,这样非常方便读者检索。而这个步骤正好同时完成了目录整理的过程:只需对树形提纲进行适当提炼,就可以轻松成为我们的目录索引了。可以参看本文的目录索引,其实也就是本文的树形提纲了。
准备周边素材
巧妇难为无米之炊,没错,提纲有了就相当于锅碗瓢勺等吃饭的架子都已准备妥当,就差最重要的“食材”就可以“做饭”(写作)了。因为我们已经有了立意和树形提纲,围绕它们我们就可以明确知道接下来要写什么内容,那么拿什么来支撑内容呢?可以参考以下可以准备的素材分类:
关键概念
关键代码
规范要求
案例支撑
图片解释
互动demo
其实周边素材可以有很多,在前期准备的时候可以“贪多”,最后再进行“过滤”即可。而收集素材、审视素材的时候,会促进我们来来回回地进行学习和思考。这个过程对作者来说是十分有益的,不仅能把自己的经验沉淀在纸面上,也同时在这个过程中不断“验证”、“证伪”、“升华”自己的技术经验,甚至碰撞出一些令人激动的“思维火花”。
调整树形提纲
从树形提纲形成之初,它就可以不断进行调整。不管在准备周边素材还是在写作中或写作后,都可以在当下按照自己的理念进行调整,或裁剪或丰满。这有点儿像我们写程序时,不断调整参数以观察不同的输出结果,直到结果令人满意,那么树形提纲就“定型”了,与之关联紧密的“目录索引”也可轻松产出。这样我们就可以有条不紊地开始写作了。因为我们手里有了“树形提纲”这个写作向导,就不用再为不知道写什么,不知道是不是跑题了而烦恼。
写作中
我们顺着“树形提纲”有条不紊地进行叙述就可以进行文章主体部分的写作了。但有的同学可能依然会感到困惑,还是不会写怎么办?其实这里我认为涉及到一个写作能力和技巧培养的问题。写作能力的培养绝不是一朝一夕的事情,所以这里简单地抛砖引玉,从写作基本功、技术难点阐述以及提炼方法论这三个方面,简单说下我对技术写作的理解。
写作基本功
写作基本功其实是我们从识字开始就不断练习的一种技能。我们平时读文章,常常会感叹有些作者的文笔很好。其实好的文笔一定是建立在良好的写作基本功之上的。市面上有很多专门的书籍和课程来讲怎么写作,我们可以专门去学习这门“技艺”,当然多看多练多模仿是少不了的,这里就不再展开这些内容,主要列下需要注意的点:
格式:段落、标点、字体、字号、数字等
语法:主谓宾、转折、关联等
段落:总分、层次、点题等
逻辑:清晰、自洽、完整、无歧义、用词统一等
对仗:时间对仗、层次对仗、递进对仗等
技术阐述技巧
这里重点提一下技术方面的阐述技巧,因为我们写的是冷冰冰的代码,它本身没有过多的“人性”,而技术文章的使命就在于此,让读者不必“过深”地阅读代码,就可以从代码那“百折千回”中领悟到你的“意图”。一篇好的技术文章往往就是在这个环节做得非常出色,总是能让读者轻松领悟到代码意图,如果能让读者发出:“原来是这样!cool!”如此的感叹,那就是好的技术文章所带来的魅力了。技术难点的阐述的难度往往是由技术本身的难度带来的,因为“晦涩难懂”的代码转化成“通俗易懂”的文字,是需要极强的技术能力和文字表达能力的。那么除了能力的培养提高之外,有没有什么方法可以让我们在写技术难点时更有指导方向呢?下面我列举了几种方法,供大家参考。
举例法
常用的手段之一就是举例子,通过通俗的例子来解释代码逻辑。例如数据结构queue(队列)和stack(栈),我们就可以生活化地解释它们。
queue:就是在排队在“鲍师傅”窗口买蛋糕的队伍,先来的人买完之后先离开,这对应着queue中的值先进先出的特性。
而stack:就是“老鹰抓小鸡”中的队伍,老鹰要从队伍尾巴处把人一个一个抓出去,这对应着stack中的值后进先出的特性。
举例子其实有很多手段,可以举生活的例子,也可以举复杂代码简化后的例子,还可以跨学科举例子。只要有利于读者通俗易懂并准确get到核心的例子都是好例子。
重点突出法
很多时候,技术文章因为技术点很多,而删减技术点又不利于整体阐述。这时候,重点突出法非常管用。因为在茫茫的大草原中让别人发现一颗稀有的小草太难了,那我何不在这颗重要而稀有的小草旁边立块牌子,并写上字“嘿!看过来,我在这!”呢。对于文章想要强调的重点,一定要重点突出出来,怎么可以突出呢?可以参考以下手段来突出重点:
相关重点给予足够的篇幅
单独成段
提炼小标题
视觉加强:加粗、字体颜色、增加背景色等
图像法
一图胜千言,绝非虚言。读者对图的直接感知度往往要比干巴巴的文字要强很多。一张好的图可以解释大段文字才能说清楚的东西,甚至文字无法表达的“意境”同样可以使用图来“表意”。但是前提是图是精心设计并准确表意的,如果滥用图或者图使用不得当则会适得其反。即使我们不知道画什么,计算机领域里也依然有迹可循,由于图强大的解释力,软件开发中层出不穷地建立了很多有关“图”的规范:UML、流程图、实体图、数据流向图、原型图等等。善于利用这些图会使得我们的“技术解释力”更上一个台阶。
交互法
交互法和举例法有些像,但是举例法大多是“静态”的,而交互法则更具生命力,它是可以“动态”交互的。例如我们在阐述多个实体的关联关系的时候,我们可以提供给读者一个交互动画,让读者用连线的方式来理解实体间的关联关系,这种让读者主动参与到技术学习中的方式,往往比被动地接受有用得多。交互法虽然制作成本大,但对于教学类的文章是效果非常好的阐述和演示工具。
提炼方法论
当我们写完文章主体部分后,写一个让人印象深刻的总结是非常有必要的。而这个总结得广度和深度是可以发散的,也就是说可以从文章的点形成总结的面,从文章的面形成总结的体。从文章本身抽象到某个领域的通用规则,也就是提炼方法论。当然,我非常不建议强行提炼,而当这篇文章真的激发了你的深度思考并有所结论时,快,千万别犹豫,把它总结提炼出来,这对于作者本人和读者都将大有裨益。
写作后
当文章的主体写作完毕,还是有一些方面需要继续处理,这里重点讨论三个方面。
通读找错
写完文章,需要通读文章,并在通读的过程中寻找错误,例如错别字、不通顺语句、表意不明等。
查漏补缺
在通读文章的过程中,继续查漏补缺,多余的删除,没阐述完整或清晰的则需要增加。另外如果你的文章引用了规范、他人著作等,一定要加上引用说明,一来遵守被引用方的版权,二来为想要深入引用资料的读者提供检索便利。
升华立意
升华立意在技术文章中的确不多见,但是在某些特定场景下则可使文章更具“饱满感”,例如把技术文章和公司战略、技术前沿突破等方面结合起来,会使得技术文章同样可以“发光发彩”和“走进人心”。
结束语
其实如何写好一篇技术文章这个问题的答案很简单:技术好 + 写作好。而本文着重阐述了我对如何“写作好”的看法与总结。而这些大多都是“术”,想要达到更高境界,必须要悟“道”:培养自我独有的感悟能力。
那么如何才能“悟道”呢?我也还在悟的路上,这里分享三个个人看法:
❝借他山之石:站在高手的肩膀上,多学习借鉴他人的写作手法和思路,取其精华去其糟粕。
行自我之思:勤思考多总结,自我思考得够多够深,才不会“思到用时方恨少”。
走勤奋之路:万丈高楼平地起,一点一滴积累,勤耕不辍。
由于本人能力所限,请大家对本文不吝指正,望共同进步。