本文已参与「新人创作礼」活动，一起开启掘金创作之路。
写技术文章的想法很久之前就有了，但是每每提起笔时，感觉自己言之无物，最终都放弃了。现在准备总结一下工作以来所学的知识输入一些文章，首先要搞清楚怎样写好一篇技术文件文章。在参考了网络上的一些文章之后写下这篇文章，如有侵权请联系删除。
1、什么是好文章
1.1 阅读量 ≠ 文章质量
有些文章标题比较吸引眼球，有些话题自带流量，有些内容的受众比较广，所以有很高的阅读量，但这并不代表文章本身的质量。
前几天无意翻到一篇《超长用户行为建模在躺平家居内容推荐中的应用实践》，我觉得写得不错，但是内容我完全看不懂，是专业领域的文章，受众不多，有上千的阅读量就已经很不错了。但是另一篇《如何画好一张架构图？》就有超过 3W 的阅读量。当然反例也有很多，就不再列举了。我自己写的几篇讲技术细节的文章，就没有讲技术对比、讨论技术发展的文章阅读量高。内容越专越细，能读下来的人就越少，但并不代表文章质量不高，反之亦然。
技术文章盲目追求阅读量和点赞数不是件好事，所以第一个小建议就是不要太关注阅读量和点赞数，写的文章对别人有用，才是最有成就感的。至于除了阅读量和点赞数以外，还有什么指标可以衡量一篇文章的好坏，欢迎大家留言讨论。
1.2 文章要长长长长长（也别太长）
我翻了几篇阿里技术公众号里阅读量较高的文章，各种话题都有，风格差异很大，但是有一个共同点：文章写得很长。这并不代表文章写了很多字就是好文章，背后的真实含义是：好文章的内容足够丰富。
内容丰富详实，这是一篇好文章的必要条件。还有一个条件是要包含真正有价值的内容，不能含太多水分。
提供一个小技巧：如果你写了一篇文章但是觉得内容很单薄，可以先当成一篇笔记存起来，等有了更丰富的积累之后再整理成文章。扩展文章内容的方法，并不是添加无意义的空话套话，而是根据文章探讨的问题延展开来。
比如说介绍自己解决的一个老大难 Bug，可能真正修改的代码并没有几行，把过程讲出来也不过寥寥几段。这时候你就可以再分析一下 Bug 存在的原因，为什么一直拖到现在，再思考一下如何避免这类问题，遇到同类 Bug 怎样快速排查。这样自己想问题的角度更全面了，文章内容也更丰富了。
比如你想介绍一项自己在学的新技术，发现自己写的东西其实就是官方文档的简化版，去重之后几乎什么都不剩了。这时候不要再继续抄文档了，把自己的思考总结先记下来，继续学习技术，持续记录新的内容，有更全面的了解之后，再写文章。
1.3 清晰的叙事结构
优秀的技术文章，结构一定是清晰的，有可能目录就代表了某个技术体系，或者代表了解决问题的思路。
优秀的内容 + 清晰的结构 = 好文章
能把技术问题讲清楚，就很考验表达能力，这是大部分程序员比较欠缺的。对于技术类文章，常见套路也不多，我简单介绍两类吧：
- 线性叙事，逐步推进：适用于介绍排查问题的过程、分享设计思路、介绍项目的迭代进展。
- 结构化叙事，层层展开：适用于讲规划、做总结、画大图、介绍一整套技术方案。
1.4 线性叙事，逐步推进
对于这类文章，读者是应该按顺序一段一段看的，写的时候脑海中模拟读者的视角来写。这类文章的小技巧就是：模拟读者视角，设定一条主线，有节奏的向前推进。和讲故事差不多，每一步的推进要有逻辑，要保持思路不要断掉。
1.5 结构化叙事，层层展开
除了按顺序看的，还有不按顺序看的文章吗？有的，尤其在专业的技术文章里很常见，大部分是“总-分”的结构，先讲整体框架，再分章节介绍各个部分。
比较常见的是那种总结型的文章，比如《平台建设的7大问题：蚂蚁AI平台实践深度总结》和《救火必备！问题排查与系统优化手册》，就是翻阅性质的书，可以通读一遍，也可以只看其中一段，之后遇到相关的问题，根据目录跳着阅读。
对于文思泉涌的人，可以一口气把整篇文章写完。但实际情况是，很多时间被碎片化，可能还要引用一些专业内容，可能需要查资料，写文章的过程会被中断。这类文章不是一口气写完的，是先搭架子再填充完整的。其实写起来也很简单：先想好标题，再划分好目录结构，再一段一段的填充内容，最后再润色一下连接部分。文章可以不按顺序看，也可以不按顺序写。
我自己写的《关于浏览器、Weex、Flutter 的比较和思考》这篇文章就是先划分好了目录，再一点一点填充的，写文章的时间跨度也比较长，想起来一点写一点。
线性叙事是个链表，结构化叙事是树。
2、为什么写文章
为什么要写技术文章？写技术文章对自己有什么收益呢？
2.1 巩固知识、形成自己的技术沉淀
著名的费曼学习法费曼学习法强调“以教代学”，在教授知识的时候发现自己的薄弱之处，然后针对性的学习，以此往复，最终完全掌握知识。写文章的本质是一种“以写代想，以想促进，以讲验真”的技巧，在写作的过程中让自己对知识理解的更加深入。
2.2 分享和传播知识
技术文章的首要作用就是传播知识，相信大部分人写技术文章的目的就是把自己所学习到的知识分享出来。如果大家都愿意积极分享知识，让我们需要搜索知识的时候也会变得更加简单。
2.3 提高个人的技术影响力
无论是公司内部分享还是在互联网分享都会让更多的人认识你，高质量的技术文章会增强读者对你的了解和信任，从而提高自己在圈内的影响力，更容易被发现。
2.4 获取额外收入
在自媒体的时代，写文章是程序员有效的变现手段之一，例如某丙、某皮就是这方面的佼佼者。
3、怎样写好文章
3.1 确定选题
3.1.1 题材来源
-
日常记录和总结：日常工作中，对遇到的问题、完成的项目及时的记录、总结，久而久之就自然积累了写作的题材。
-
深耕领域技术：在自己擅长的特地领域技术上，不断深耕，逐渐成为领域专家，并把阶段性的学习成果输出成一系列的文章。
-
源码走读分析：对当下热门框架、工具的源码进行分析、解读，沉淀为源码分析类的文章。
-
国内外新热文章：对国内外的新热技术进行尝鲜，分析利弊，并落地到实际的项目中，输出技术实践类文章。
-
读书分享：读完技术书籍后，加以总结，沉淀精髓，总结为文章，带领读者快速的了解该书的内容。
3.1.2 受众分析
不同的受众关注点存在差异，只有关注用户的需求，针对性的写作，才能写出口碑爆棚的好文章，所以首先要确定你的受众是谁？是领导，还是技术、产品，还是同一个技术通道的同事，不同的受众表述方式会有些不同。
对于大多数技术文章来说，常见的受众有：
- 相同技术类别： 有足够知识背景，适合使用专业术语深入探索某一个领域逻辑。
- 不同技术类别： 有一定知识背景，适合架构分享、项目总结类文章。
- 产品、运营：技术背景相对薄弱， 适合深入浅出，科普介绍技术的实现和目的。
结合自身题材来源、受众分析，最终确定一个自己擅长且有受众的选题，然后深挖用户痛点，写出对受众有价值的文章。
3.2 收集资料&素材
确认选题后首先要对题材有一定了解，根据不同题材的来源，收集对应的资料、素材，才能保证文章的高质量，这是写好一篇技术文章的基石。
通常我们可以通过以下几种方式来进行资料的收集工作：
- 平时知识储备： 平时读书笔记、项目记录，知乎 和 公众号相关文章的收藏、总结、思考等。
- 请教该领域的专家，是否有推荐的书籍与资料，当前主题相关知识的关键要素有哪些，主要挑战有哪些。
- 善用搜索引擎，必要时阅读相关领域前沿学术论文期刊，以图获取最可靠专业的技术信息。
做好收集资料的目的在于：
- 保证文章的可靠度、专业性。
- 至少保证专业对齐甚至超出行业领先水平，以提供足够的价值。
3.3 确定文章结构
文章的结构（框架），可以理解为先写什么，后写什么，怎么开头，怎么结尾。通常写文章之前首先确定的是标题，其次就需要确定结构。结构可以通过文章的目录体现出来。我写任何一篇文章之前，都会先确定文章的目录，再往对应的章节中填充内容（并不一定按顺序）。一篇文章有目录的好处是很明显的，首先可以让读者很快就对整个文章的脉络比较清楚，其次也方便读者直接跳到自己感兴趣的章节进行阅读。问题是，应该怎么确定文章的结构呢？接下来推荐几大利器。
3.3.1 金字塔理论
其核心思想是：任何事情都可归纳出一个中心论点，中心论点可由三至七个论据支持，这些论据本身也可是个分论点，被三至七个论据支持，如此延伸状如金字塔。
金字塔原理的要点可以概括为：
- 结论先行。一次表达只支持一个思想，最好能够出现在开头。
- 以上统下。任何一个层次的要点都必须是它下一个层次要点的总结概括，直到最后一个层级的内容是客观事实或数据为止。
- 归纳分组。 就是每一组要点必须要属于同一个范畴。
- 逻辑递进。每个要点都需要按照一定的逻辑顺序进行排列。
那么对于写文章来说，我们可以这么做：
- 观点先行：在导语和开篇中就亮出观点，吸引读者往下看。
- 先有提纲：先列目录，再写内容。
- 承上启下：每个段落之间想想怎么做合适的过渡和转折。
- 结尾升华：在文章末尾最好总结全文，拓展思考。
3.3.2 结构化思维
任何一篇文章都是结构化思维的产物。很多人觉得写东西太难，其实症结不在于对文字的把握，而恰恰是对缺乏对思维结构的把握。所有文章，必然要有“中心思想”，这就是结构化思维中的“确立目标”；为了表述这个“中心思想”，必然要分段陈述，各个段落有各自的“段落大意”，来支持“中心思想”，这个就是结构化思维中的“资源分析”；提纲出来以后，分段展开陈述形成文字，就是结构化思维中的“制订计划”。大家写文章写着写着，要不写不下去了，要不就是跑题了，其实在遇到的障碍正是在“结构化思维”训练中的不足。
结构化思维是以事物的结构为思考对象，来引导思维、表达和解决问题的一种思考方法。简单来说就是顺着事物的结构和脉络，从整体思考到局部，借助一些框架来思考，将碎片信息进行系统处理。具体操作上，结构化思维要求我们在思考分析解决问题时，以一定的范式、流程顺序进行，首先以假设为先导，对问题进行正确的界定，假设并罗列问题构成的要素，其次对要素进行合理分类，排除非关键分类，对重点分类进行分析，寻找对策，制订行动计划。
结构化思维的本质是信息熵——把知识的有序度最大化。
以下是结构化思维的一些要点，可以发现与金字塔原理有某些重叠的部分。
- 自上而下。分析的过程通常是数据->事实->观点这样的顺序，而表达的过程则相反，先摆出观点。
- 层次清晰。把相关议题在一个章节内说清楚，分清楚议题的层次。
- 结构简单。表达的结构不宜太过复杂。一个简单的训练方法，叫“重要的事情说三点”。也就是列出与议题相关的三个议题。
- 重点突出。不要试图传递过多信息，要把最想传递的信息突出出来。
如何锻炼结构化思维，推荐以下的步骤。
- 第1步，头脑风暴，将所有想法穷举。
- 第2步，将穷举出来的所有想法，分类归纳。
- 第3步，基于分类，提炼标题或结构。
- 第4步，做一些补充。
最后，要善用工具：思考时养成画思维导图的习惯。
3.3.3 MECE
MECE，是“Mutually Exclusive , Collectively Exhaustive” 英文首字母的缩写。中文的意思是“相互独立，完全穷尽”，它是很重要的结构分类原则。要素之间既相互独立、完全穷尽，让结构划分更加逻辑清晰。它是自上而下方法论的利刃，也是思辩者日常修炼的最为关键的科目。在写文章方面，当我们手里有很多信息不知道如何归纳整理时，可以使用 MECE 原则对其进行归类整理，同时还可以扩展思路，发散思维。
MECE 原则有五种分类法:
- 二分法。 这个分类方式在日常生活中比较常见，其实就是把信息分成
A和非A两个部分。 - 过程法。也就是按照事情发展的时间、流程、程序，对信息进行逐一的分类。
- 要素法。其实都是把一个整体分成不同的构成部分。可以是从上到下，从外到内，从整体到局部。 这种分类方法是用于说明事物的各个方面特征的。
- 公式法。可以按照公式设计的要素去分类，只要公式成立，那这样的分类就符合
MECE原则。 - 矩阵法。比如把你的工作分成以重要紧急、重要不紧急、不重要但紧急、不重要也不紧急。然后可以把它们填到4个象限当中去，这种分类方式就叫做矩阵法。
3.3.4 奥卡姆剃刀法则
前面讲的都是如何“做加法”，再谈谈“做减法”。奥卡姆剃刀原理又被称为“简约之法则”，它的提出者说过这样一句话“切勿浪费较多的东西，去做用较少的东西，同样可以做好的事情。”奥卡姆剃刀定律认为保持事物的简单化是对付复杂与烦琐的事情的最有效的方式。它的理论被概括起来就是一句话：“如无必要，勿增实体”。
在写文章方面，我们同样应该秉持这样一种理念，应当追求文章结构的简洁性，不应当试图在文章传递过于杂乱庞杂的信息，对于不能服务于文章中心思想的内容应该果断摒弃掉。因为这会给读者平添理解成本，而无助于中心思想的表达。
这一点大家应该都有切身体会，如果看到一篇文章，其目录结构过于复杂，或段落信息量过大，可能第一时间就有点想放弃了。 这里的建议是：
- 结构简单原则。按照金字塔原理确定的结构，应该是以中心思想为核心展开的，整个结构给人的感觉是“内聚”和简洁的。
- 文字简省原则。尽量使用较短的语言和篇幅来描述一个问题。
- 通俗原则。尽量少写生僻的文字和晦涩的内容，使用平易近人的语言，追求文章的通俗性。
4、写作技巧
4.1 碎片化记录，结构化整理
大部分人的问题是不知道该写什么，即使已经有足够的积累，有明确的话题要写，也不知道该如何下笔。这就要靠日常的积累了。
在平时工作的时候，可以建个文档库，把日常的一些琐碎的想法记录下来，随时写随时存。我是用手机的便签 App 随手记东西，比较喜欢它的语音转汉字功能，工作相关、生活相关，随时随地想起任何话题都可以记录下来。
在有了明确话题，准备写文章之前，先把各种碎片化的记录收集起来，形成一份“素材”文档，然后梳理文章脉络，把素材应用进去。操作起来很简单，刚开始的时候会遇到前后不通畅的问题，那就不要直接复制素材的内容，重新换个表达方式写出来。多练习练习就好了。
4.2 刻意练习，先写再改
有了素材之后，平时可以专门练习写作能力，先写一小段话，明确的描述一个观点，然后不断修改。练习把做的事情描述清楚，说话的方式简单点，不要用太多高大上的词汇。最关键的部分在于：写完花五分钟再改一遍！读一下是否通顺，有没有把问题讲清楚。反复修改才是提升写作技巧的关键。
4.3 一图胜千言
人类对于信息的接受方式决定着图片比文字更易于被接受。所谓“文不如数，数不如表，表不如图”。写文章中好的实践往往会使用大量的图片来辅助表达自己的意思。全部是文字甚至代码的文章，通常会天然地使人产生抗拒感。
4.4 写作工具
工欲善其事，必先利其器。
4.4.1 markdown 工具
写文章是通常面对多平台发布的问题，现在主流平台都支持 markdown 语法，所以 markdown 是我们跨平台发布的最佳选择。我最常用的工具是：typora。
4.4.2 画图工具
一图胜千言，技术文章当然少不了各种图例，在这我把珍藏多年的画图工具分享给大家。
4.4.3 代码处理
硬核技术文章当然少不了各种代码展示，通常可以使用 markdown 中的源代码语法展示，如果追求美观，可以使用 carbon 对代码进行美化。
4.5 写作规范
下列规范来自于中文技术文档的写作规范。
4.5.1 标题
标题分为四级。
- 一级标题：文章的标题
- 二级标题：文章主要部分的大标题
- 三级标题：二级标题下面一级的小标题
- 四级标题：三级标题下面某一方面的小标题
原则：
- 一级标题下，不能直接出现三级标题。
- 标题要避免孤立编号（即同级标题只有一个）。
- 下级标题不重复上一级标题的名字。
- 谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节。如果三级标题下有并列性的内容，建议只使用项目列表（Item list）。
4.5.2 文本
字间距
- 全角中文字符与半角英文字符之间，应有一个半角空格。
- 全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。
- 英文单位若不翻译，单位前的阿拉伯数字与单位符号之间，应留出适当的空隙。
- 半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。
句子
- 避免使用长句。
- 尽量使用简单句和并列句，避免使用复合句。
- 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
- 避免使用双重否定句。
英文处理
- 英文原文如果使用了复数形式，翻译成中文时，应该将其还原为单数形式。
- 外文缩写可以使用半角圆点(
.)表示缩写。 - 表示中文时，英文省略号（
...）应改为中文省略号（⋯⋯）。 - 英文书名或电影名改用中文表达时，双引号应改为书名号。
- 第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。
- 专有名词中每个词第一个字母均应大写，非专有名词则不需要大写。
4.5.3 段落
原则
- 一个段落只能有一个主题，或一个中心句子。
- 段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为中心句子服务。
- 一个段落的长度不能超过七行，最佳段落长度小于等于四行。
- 段落的句子语气要使用陈述和肯定语气，避免使用感叹语气。
- 段落之间使用一个空行隔开。
- 段落开头不要留出空白字符。
引用
- 引用第三方内容时，应注明出处。
- 如果是全篇转载，请在全文开头显著位置注明作者和出处，并链接至原文。
- 使用外部图片时，必须在图片下方或文末标明来源。
4.5.4 数值
半角数字
阿拉伯数字一律使用半角形式，不得使用全角形式。
千分号
数值为千位以上，应添加千分号（半角逗号）。
货币
货币应为阿拉伯数字，并在数字前写出货币符号，或在数字后写出货币中文名称。
数值范围
表示数值范围时，用波浪线（～）或一字线（—）连接。参见《标点符号》一节的“连接号”部分。
带有单位或百分号时，两个数字建议都要加上单位或百分号。
变化程度的表示法
- 数字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。
- 数字的减少要使用“降低了”、“降低到”。“了”表示增量，“到”表示定量。
- 不能用“降低 N 倍”或“减少 N 倍”的表示法，要用“降低百分之几”或“减少百分之几”。因为减少（或降低）一倍表示数值原来为一百，现在等于零。
5、常见误区
5.1 所有的主题都适合通过写文章来表达
知识的沉淀和分享并不一样要通过写技术文章来传达，有的更适合通过技术文档记录，而有的更适合通过 PPT 来表达。
5.2 阅读量和收藏量等于文章质量
阅读量和收藏量这两者最多只是正相关。比如有的文章标题吸睛，或者话题自带流量，又或是受众面广，阅读量自然比较高。而另外一些因为太过专业导致受众面小的文章可能阅读量不佳，但其实是“沧海遗珠”也很有可能。因此一般的社区都会有小编人工推荐的功能，可以避免这类文章被埋没。
5.3 写技术文章和写论文方式一样
技术文章的写作和论文有所不同。首先论文行文非常正式，技术文章相对更为通俗大众，因此可以使用较为接地气的语言，还可以加入具有表现力的图片（甚至表情包）。论文需要追求学术上的绝对严谨性，而技术文章重在分享，不一定要做到面面俱到，滴水不漏（当然也要做到基本的技术严谨性）。
6、总结
本文从是什么、为什么、怎么做等几个方面介绍如何写好一篇技术文章。不过最重要的还是文章能否为他人创造价值，能否解决他人最迫切的现实问题
最后感谢您抽时间阅读，期望本文能帮助您在写作上有所进步。
