教你写好技术文章

前言

对于软件工程师来说，编码能力的重要性自不必说，技术写作的能力也相当重要。一篇好的设计文档能够指导需求的开发测试，提升软件质量；一篇好的用户文档能够帮助用户迅速熟悉软件的使用方法；一篇好的技术博文可以让人耳目一新，受益匪浅；一篇好的经验总结可以让新手们少走弯路。

技术写作的目的是让读者能够顺利地使用一个软件或理解一项技术或弄懂业务流程。它与创作型写作的最大区别在于，技术写作并非为了取悦读者，而是追求以简洁和精确的文字去阐明事实。

一篇好的技术文章应该能够让符合条件的读者，在良好的阅读体验下，理解甚至掌握文章所要传达的内容。

技术写作是一项学问，很多同学或多或少都有写些技术文章的想法，但因为缺乏一些基本的写作技巧，常常无从下手。本文将给出一些技术写作的建议，力求让软件工程师们能够写好技术文章，爱上技术写作。

为什么要技术写作

前言有提到，一篇好的技术文章能够给读者带来众多益处，其实，技术写作也同样能让作者本身收益颇丰。

提升表达能力

如何组织文章，如何将复杂的技术原理通熟易懂地表达出来，这都非常考验人的表达能力。

加强架构和逻辑思维

文章如同软件，也有架构和逻辑。博士们的架构和逻辑思维之所以普遍强大，一个很重要原因是他们都经过了严格的论文写作磨练。当我们把文章写好时，架构和逻辑思维会得到增强，软件设计和开发能力也能随之提高。

加深对技术/业务的理解

想要写好技术文章，必须要熟悉写作的内容，自然地要求作者在写作前做足功课，如此一来也就加深了对相关技术/业务的理解。

展示自我

通过技术文章来分享知识是一个很好的展示自我的途径，让大家知道你当前熟悉的领域，逐渐扩大自己的影响力，对后续的职业发展可以起到很大的帮助。

心灵愉悦

在公开平台上发表技术文章，收获很多浏览量，被读者评论，得到读者点赞和收藏，这些都能够让人得到心灵上的愉悦。

如何开始技术写作

所谓万事开头难，对习惯于与代码打交道的软件工程师来说，要开始与文字打交道的技术写作，很难。相信很多同学都遇到过憋了几个小时都没写出几个字，或者一直在纠结写什么内容的窘境。其实，只要找到一些方法，着手技术写作，并没那么难。

从记录学习/工作内容开始

可以先从记录日常的学习/工作内容开始，慢慢习惯与文字打交道，此过程重在建立起写作的自信。

文章长短不重要

不要一开始就想着写出惊骇世俗的文章，成为最出色的技术博主。也并非只有长篇大论才算得上好的技术文章，一些问题解决记录、经验总结的短文也能给读者很大的帮助。

通过学习找到写作灵感

如果你还在为要写什么内容而焦头烂额，那么就去学习一项新的技术或者去阅读一本书吧。最好的写作时机就是刚学到知识的时候，因为这时你很清楚从零到一的过程，这也是你要传递给读者的东西。

学会做笔记

笔记是很好的写作素材，在日常的工作和学习中多做些笔记，把自己的灵感记录下来，后面写作起来也会轻松许多。

写作的三部曲

第一步：立下写作目标

写作的第一步是立下目标，明确要写哪一类的文章，并朝着目标去写作。比如，立下了介绍Java中HashMap数据类型的目标，就不要在文章上描述JVM的垃圾回收原理，这是混淆了写作目标。

第二步：确定受众读者

写作的第二步是确定受众读者，只写这类读者可以接受的知识。比如，要写一篇题目是《从零开始学习Java语言》的文章，这明显是一篇针对Java初学者的文章，那么就不要在文章里剖析JVM内存管理的实现源码，这是混淆了文章受众。

第三步：组织文章

组织文章就是根据中心旨意，把要表达的知识串联成一篇条理清晰的文章。很多新手都会面临“心中想法万千，却无从下笔”的困境，这就是缺乏文章组织导致的。《文心》一书中有提到：

对于文章的组织，也不妨举出一个总方法来，那就是 ‘回问自己’ 四个大字。

我们可以通过“回问自己”的方法来组织文章，以《教你写好代码注释》一文为例：

“是为了要说些什么才写这篇文章的？”

—— 为了总结些写好代码注释的方法。这样文章的中心意旨就明确了。

“中心意旨在我们意念中间是怎么来的？”

—— 读到《A Philosophy of Software Design》一书中关于代码注释的章节深有感触，想分享给大家。这样文章依据的材料范围也就确认了。

“这个材料可以增加中心意旨的力量吗？”

—— 书中关于high-level注释和low-level注释的例子可以很好地体现“什么是好的代码注释”这个旨意。这样就可以不断筛选出好的素材，文章的主要内容也就确认了。

“还有更简练通顺的表达吗？”

—— 这样写好像更通顺一些。这样经过不断的修正，一篇文章也就出来了。

一些技术写作建议

1 熟悉写作内容

作为文章的作者，你需要比读者更熟悉写作内容。可以不是相关领域的专家，但至少能够将知识清晰表达出来，并且能够回答大部分读者的问题。这就要求在写作之前，花时间去阅读相关文章、书籍，甚至是请教专家。

2 写作前先列大纲

文章不仅仅是把内容罗列出来，要注重知识的表达，因此需要一个清晰的文章架构。在写作前先列出大纲，能够帮你理清写作思路，确认内容是否符合逻辑，构建清晰的文章架构。多想想，哪个内容需要先阐述？段落的顺序要怎么排？哪些知识需要更多的解释？哪些点到为止即可？

3 精简文字

技术写作不是剧本小说，不需要反转曲折的剧情，更不需要含沙射影的表达，它追求的是直接、实用、清晰明了的表达风格。没必要使用过于复杂的文字去描述技术原理，这只会让它们更加难以理解。使用简洁的文字，多用短句，能够让文章可读性更好。

4 多举例子

避免通篇介绍技术原理的写作，这会让文章过于枯燥，内容也晦涩难懂。要多举例子，它不仅能让技术原理更易懂，也能让主题更加深刻。比如在《教你写好代码注释》中，通过举例正反面的代码注释，更能让读者对好的代码注释产生共鸣。

5 善用图表

有时候，我们会遇到很难用文字，或需要用很多文字才能描述清楚的东西，比如复杂的业务流程和模块依赖。这时可以使用图表来可视化表达，一张恰当的图表能够清晰地阐明技术原理，胜过千言万语。

一些画图软件推荐

• 适合新手：MicroSoft Office PowerPoint、MicroSoft Office Visio、Apple Keynote
• 在线画图：Draw.io、ProcessOn、Excalidraw
• 代码绘图：PlantUML
• 手绘风格：Apple Keynote、Excalidraw
• 高级玩家：Sketch、Lunacy

6 代码分段

在深度剖析一些技术原理或系统框架时，我们往往都会涉及源码分析，切忌直接在文章中贴上上百行的代码，然后在代码前/后用一段文字对其说明。这会导致读者为了将代码和说明对应上，而频繁上下翻页，严重影响阅读感受。

反面教材：

...
inline void* oopDesc::field_base(int offset) const { 
return (void*)&((char*)this)[offset];
}
template  inline T* oopDesc::obj_field_addr(int offset) const {
return (T*)field_base(offset); 
}
// 剩余上百行的代码
...

由上述代码片段可知，每个field在oop中都有一个对应的偏移量（offset），xxx。

更好的方法是将代码分段讲解，并在在其中穿插关键注释。

正面例子：

// 获取field前需要先判断是否采用了指针压缩技术，先根据offset调用obj_field_addr
// 得到field的地址，然后调用load_decode_heap_oop得到实例
inline oop oopDesc::obj_field(int offset) const {
return UseCompressedOops ?
 load_decode_heap_oop(obj_field_addr(offset)) :
 load_decode_heap_oop(obj_field_addr(offset));
}

oopDesc::obj_field方法主要用于xxx。

// 基础类型特有的实现与obj_field_addr类似，只是转型成特有的基础类型指针
inline jbyte* oopDesc::byte_field_addr(int offset) const {
return (jbyte*)field_base(offset); 
}

oopDesc::byte_field_addr主要用于xxx，在xxx时会被调用。

7 反复修正

好的文章都是经过反复的修正才诞生，不仅仅局限于错别字和用词的修改，要以读者，甚至是审稿人的视角去审视整篇文章。怎么才能让这段内容表达更清晰？哪些知识需要延展？哪些片段可以裁剪掉？

养成在发布前仔细阅读一遍文章的习惯，杜绝低级错误，这也是对读者最大的尊重。

8 做好排版

如同代码需要分段讲解，文字也需要分段，一大段的文字容易让人觉得枯燥。对重点语句/词语需要加粗突出；善用标题、有序/无序列表来罗列知识点，让文章看起来更加清晰。

推荐使用markdown进行技术写作，它排版简洁美观，语法简单，而且绝大多数的平台都支持markdown格式的文章发布。另外，还可以使用markdown-nice等排版工具自定义文章背景、色彩、字体等，提升阅读观感。

9 读好的文章

养成读好文章的习惯，学习他们的写作方式，不断提升自己的写作技巧。

总结

《文心》将文章写作归结为三个阶段：习作、应用和创作。

习作只是法则与手腕的练习，应用之作只是对付他人和事务的东西，创作才是发挥自己天分的真成绩。

技术写作也一样，第一阶段习作，对应读书笔记、经验分享等总结类文章；第二阶段应用，对应工作中的设计文档、用户文档等指南类文档；第三阶段创作，对应类似《对XXX领域未来发展的看法》的这类文章，这往往也要求作者具备深厚的知识储备。

这三者之中，最基本、最重要的是习作。只有当习作到了相当的程度，才能有应用，也才能谈得上创作。

上面介绍了很多写好技术文章的方法，但最简单，也是最有效的方法是：不要停止写作。

参考

• 文心, 夏丏尊/叶圣陶
• 技术文章如何写作才能有较好的阅读体验, 伍迷
• Technical Writing: Definition and Observations, Richard Nordquist
• 15 Tips to Improve Your Technical Writing, TBS Staff
• Advice for Technical Writing, Chris Coyier
• Developers: The Why and How to Writing Technical Articles, Goodness Kayode