背景

最近团队有同学提议，想探讨如何才能写出一篇优秀的技术文章。所以尽管水平实在有限，还是按照自己的经验和理解写下了这篇文章，亚历山大之余，也很高兴和大家分享一下自己对技术写作的一些思考。

希望本文可以抛砖引玉，大家从中可以有所思考和收获，就能达到本文的目的了。那么，写好一篇技术文章对我们有什么用呢？

我觉得有三点：

• 第一点，可以更好地分享传播技术方案，让读者认同赞赏你的文章；

• 第二点，通过文字表达提升个人的表达能力，在做技术分享和演讲时提升效果及魅力；

• 第三点，通过整理技术文章，主动对技术深入思考剖析，提升个人的技术广度和深度能力。

那么，接下来我重点分享下我实践中的写作流程。

写作流程

写作流程，大体上可以分为：写作前的准备工作、写作中的注意事项和技巧以及写作后的提升工作。

通过对这三个阶段的打磨，相信你就可以写出一篇“令人满意”的技术文章。

写作前

所谓万事开头难，所以写作前的充分准备工作，可以帮助你快速进入写作状态，准确明晰写作内容。让我们通过以下手段，告别写作开始时的“提笔皱眉”，体验一把“下笔如有神”。

确定立意标题

我认为立意和标题应该是先确定清楚的，要非常明确地知道自己要写什么内容，这个“什么”其实并没有那么简单确认，可以参考以下罗列的确认要素：

• 内容传达的目的是什么？

• 内容关键字是什么？

• 内容触达的范围是什么？

• 内容的重点是什么？

最后，通过对立意的分析思考，形成一个立意明确的标题。不要小看这个标题，这个标题是文章的“门面”，有时候甚至会让读者使用“一票否决权”。所以，标题也应该首先明确下来，在写作中不断围绕立意的标题进行，这样即不会产生跑题的情况，也对内容进行了充分强化。技术文章的标题，其实不用起得那么“八卦”来吸引读者，简单直接即可。可以参考以下罗列的标题要素：

• 紧扣内容立意

• 简短清晰

确认目标读者

确认目标读者是非常重要的，尤其文章需要在一些特殊场合中进行发布和使用。是分享技术到社区？还是给领导汇报技术方案？还是具体下发开发执行方案？不同的场景，写作的侧重点和用语都需要做相应的调整。至于如何调整，这个需要对不同的环境进行判断，并不能一概而论，可以参考不同场景下要考虑的写作要素：

• 文章中的称谓

• 读者最关心的是哪部分？过程？结果？还是数据？

• 是否需要为读者提供某些补充资料？

形成树形提纲

在确认立意和目标读者之后，我们就可以开始“下笔”了，但是我建议不要急于写文章的主体部分，而应该先形成纸面的“树形提纲”。当然，如果写作前脑子里的“布局”就已经非常清晰，也可以省略纸面工作。其实，我们写文章，尤其是比较长的文章，是应该有目录索引的，这样非常方便读者检索。而这个步骤正好同时完成了目录整理的过程：只需对树形提纲进行适当提炼，就可以轻松成为我们的目录索引了。可以参看本文的目录索引，其实也就是本文的树形提纲了。

准备周边素材

巧妇难为无米之炊，没错，提纲有了就相当于锅碗瓢勺等吃饭的架子都已准备妥当，就差最重要的“食材”就可以“做饭”（写作）了。因为我们已经有了立意和树形提纲，围绕它们我们就可以明确知道接下来要写什么内容，那么拿什么来支撑内容呢？可以参考以下可以准备的素材分类：

• 关键概念

• 关键代码

• 规范要求

• 案例支撑

• 图片解释

互动demo

其实周边素材可以有很多，在前期准备的时候可以“贪多”，最后再进行“过滤”即可。而收集素材、审视素材的时候，会促进我们来来回回地进行学习和思考。这个过程对作者来说是十分有益的，不仅能把自己的经验沉淀在纸面上，也同时在这个过程中不断“验证”、“证伪”、“升华”自己的技术经验，甚至碰撞出一些令人激动的“思维火花”。

调整树形提纲

从树形提纲形成之初，它就可以不断进行调整。不管在准备周边素材还是在写作中或写作后，都可以在当下按照自己的理念进行调整，或裁剪或丰满。这有点儿像我们写程序时，不断调整参数以观察不同的输出结果，直到结果令人满意，那么树形提纲就“定型”了，与之关联紧密的“目录索引”也可轻松产出。这样我们就可以有条不紊地开始写作了。因为我们手里有了“树形提纲”这个写作向导，就不用再为不知道写什么，不知道是不是跑题了而烦恼。

写作中

我们顺着“树形提纲”有条不紊地进行叙述就可以进行文章主体部分的写作了。但有的同学可能依然会感到困惑，还是不会写怎么办？其实这里我认为涉及到一个写作能力和技巧培养的问题。写作能力的培养绝不是一朝一夕的事情，所以这里简单地抛砖引玉，从写作基本功、技术难点阐述以及提炼方法论这三个方面，简单说下我对技术写作的理解。

写作基本功

写作基本功其实是我们从识字开始就不断练习的一种技能。我们平时读文章，常常会感叹有些作者的文笔很好。其实好的文笔一定是建立在良好的写作基本功之上的。市面上有很多专门的书籍和课程来讲怎么写作，我们可以专门去学习这门“技艺”，当然多看多练多模仿是少不了的，这里就不再展开这些内容，主要列下需要注意的点：

• 格式：段落、标点、字体、字号、数字等

• 语法：主谓宾、转折、关联等

• 段落：总分、层次、点题等

• 逻辑：清晰、自洽、完整、无歧义、用词统一等

• 对仗：时间对仗、层次对仗、递进对仗等

技术阐述技巧

这里重点提一下技术方面的阐述技巧，因为我们写的是冷冰冰的代码，它本身没有过多的“人性”，而技术文章的使命就在于此，让读者不必“过深”地阅读代码，就可以从代码那“百折千回”中领悟到你的“意图”。一篇好的技术文章往往就是在这个环节做得非常出色，总是能让读者轻松领悟到代码意图，如果能让读者发出：“原来是这样！cool！”如此的感叹，那就是好的技术文章所带来的魅力了。技术难点的阐述的难度往往是由技术本身的难度带来的，因为“晦涩难懂”的代码转化成“通俗易懂”的文字，是需要极强的技术能力和文字表达能力的。那么除了能力的培养提高之外，有没有什么方法可以让我们在写技术难点时更有指导方向呢？下面我列举了几种方法，供大家参考。

举例法

常用的手段之一就是举例子，通过通俗的例子来解释代码逻辑。例如数据结构queue（队列）和stack（栈），我们就可以生活化地解释它们。

queue：就是在排队在“鲍师傅”窗口买蛋糕的队伍，先来的人买完之后先离开，这对应着queue中的值先进先出的特性。

而stack：就是“老鹰抓小鸡”中的队伍，老鹰要从队伍尾巴处把人一个一个抓出去，这对应着stack中的值后进先出的特性。

举例子其实有很多手段，可以举生活的例子，也可以举复杂代码简化后的例子，还可以跨学科举例子。只要有利于读者通俗易懂并准确get到核心的例子都是好例子。

重点突出法

很多时候，技术文章因为技术点很多，而删减技术点又不利于整体阐述。这时候，重点突出法非常管用。因为在茫茫的大草原中让别人发现一颗稀有的小草太难了，那我何不在这颗重要而稀有的小草旁边立块牌子，并写上字“嘿！看过来，我在这！”呢。对于文章想要强调的重点，一定要重点突出出来，怎么可以突出呢？可以参考以下手段来突出重点：

• 相关重点给予足够的篇幅

• 单独成段

• 提炼小标题

• 视觉加强：加粗、字体颜色、增加背景色等

图像法

一图胜千言，绝非虚言。读者对图的直接感知度往往要比干巴巴的文字要强很多。一张好的图可以解释大段文字才能说清楚的东西，甚至文字无法表达的“意境”同样可以使用图来“表意”。但是前提是图是精心设计并准确表意的，如果滥用图或者图使用不得当则会适得其反。即使我们不知道画什么，计算机领域里也依然有迹可循，由于图强大的解释力，软件开发中层出不穷地建立了很多有关“图”的规范：UML、流程图、实体图、数据流向图、原型图等等。善于利用这些图会使得我们的“技术解释力”更上一个台阶。

交互法

交互法和举例法有些像，但是举例法大多是“静态”的，而交互法则更具生命力，它是可以“动态”交互的。例如我们在阐述多个实体的关联关系的时候，我们可以提供给读者一个交互动画，让读者用连线的方式来理解实体间的关联关系，这种让读者主动参与到技术学习中的方式，往往比被动地接受有用得多。交互法虽然制作成本大，但对于教学类的文章是效果非常好的阐述和演示工具。

提炼方法论

当我们写完文章主体部分后，写一个让人印象深刻的总结是非常有必要的。而这个总结得广度和深度是可以发散的，也就是说可以从文章的点形成总结的面，从文章的面形成总结的体。从文章本身抽象到某个领域的通用规则，也就是提炼方法论。当然，我非常不建议强行提炼，而当这篇文章真的激发了你的深度思考并有所结论时，快，千万别犹豫，把它总结提炼出来，这对于作者本人和读者都将大有裨益。

写作后

当文章的主体写作完毕，还是有一些方面需要继续处理，这里重点讨论三个方面。

通读找错

写完文章，需要通读文章，并在通读的过程中寻找错误，例如错别字、不通顺语句、表意不明等。

查漏补缺

在通读文章的过程中，继续查漏补缺，多余的删除，没阐述完整或清晰的则需要增加。另外如果你的文章引用了规范、他人著作等，一定要加上引用说明，一来遵守被引用方的版权，二来为想要深入引用资料的读者提供检索便利。

升华立意

升华立意在技术文章中的确不多见，但是在某些特定场景下则可使文章更具“饱满感”，例如把技术文章和公司战略、技术前沿突破等方面结合起来，会使得技术文章同样可以“发光发彩”和“走进人心”。

结束语

其实如何写好一篇技术文章这个问题的答案很简单：技术好 + 写作好。而本文着重阐述了我对如何“写作好”的看法与总结。而这些大多都是“术”，想要达到更高境界，必须要悟“道”：培养自我独有的感悟能力。

那么如何才能“悟道”呢？我也还在悟的路上，这里分享三个个人看法：

由于本人能力所限，请大家对本文不吝指正，望共同进步。