手把手教你写好技术文章【8K字长文】

本文由MoonWebTeam团队的owen、四月一日、HNA、challen、生皮土豆、janse合作编辑而成，部分内容来自于网络、参考文章，如有侵权请联系删除。

引言

很多人都有写文章的想法，但每次提起笔，却不知从何下手，觉得很难，本文将手把手教你如何写好一篇技术文章，为大家带来最全面、最细致、最易上手的终极指南，从此不再怕写文章。

1 为什么要写文章

思考“Why”比学习“How”更重要，在开始之前，我们从『利己』和『利他』两个角度分别来分析为什么要写文章：

1.1 对作者的好处

1.1.1 复盘学习成果，巩固知识理解

实践和输出，是检验学习成果最核心的部分，，而写作是一种低成本的输出方式。另外著名的费曼学习法强调“以教代学”，在教学的过程中不断总结，以此加深对知识的理解，而写文章，正是教学的主要途径。

1.1.2 提升思考能力

写作的根本是思考，而且是效率较高、可以积累的思考，是可以产生影响力的思考。李笑来在《财富自由之路》专栏中说到：持续写作很可能是锻炼学习能力、思考能力、分析能力、沟通能力最直接、最低成本的方式。

1.1.3 传播技术知识，积累技术资产

好的文章包括许多知识的总结、梳理，随着知识的不断积累，成为个人和团队的资产，不仅可以完善自己的知识体系，也方便其他人快速学习，利于知识的传承。

1.1.4 提升表达与总结能力

表达、沟通、总结、归纳是职场必备软技能，在写文章过程中，可以不断的锻炼自己的表达、总结能力。

1.1.5 打造个人品牌，提高影响力

自媒体时代，信息高度流通，写技术文章可以促进读者对你的了解和信任，建立个人品牌和影响力，为个人发展开拓新的天地，是我们在互联网上的另一张名片。

1.1.6 获得额外收入

知名博客“左耳朵耗子”的作者陈皓，2000 年开始写技术文章，每个月两三篇，大概 300 元的稿费，而他当时的月工资是 600 元。

知名 Python 程序员“晚枫”，坐拥 20W 粉丝，靠写文章月收入最高能达到 5w+。

这几个例子都说明：写文章是程序员有效的变现手段之一。

1.2 对读者的好处

世界的本质是价值交换，写作除了『利己』还可以『利他』

1.2.1 快速获取知识

这是阅读最直接、明显的好处。好的技术文章，往往是前人对特定领域知识筛选后的精华总结，有助于读者快速获取知识。

1.2.2 提高写作技巧

读书破万卷，下笔如有神。写文章的技巧不需要我们自己从零开始发明创造，就像学书法最开始需要临帖一样，多看、多模仿才有助于我们快速的学会如何写技术文章。

1.2.3 扩展知识边界

大部分程序员对编程知识的掌握，往往局限在自己日常使用的领域中，而通过阅读文章，可以快速的了解当下的新兴技术，有效拓展知识边界。

2 什么是好的文章

想要写出好的文章，自然要先了解什么样的文章最受大家的喜欢，才能有的放矢，按图索骥。

这里笔者所在的团队一起收集了各自认为写的最好的十多篇文章并对其进行分类。

2.1 万字长文，干货满满

动辄上万字的硬核长文，本身就承载着作者对于该技术方向的自信与专业。

内容上全面细致，让人觉得十分靠谱，总而言之，先收藏了再说。

基于 qiankun 的微前端最佳实践（万字长文） - 从 0 到 1 篇 - 掘金

为你重新系统梳理下， Web 体验优化中和图有关的那些事（万字长文）

2.2 俏皮活泼，生动有趣

有人爱读期刊论文，有人爱看短文爽文。

能把枯燥的技术点讲解的妙趣横生也是一种本事。

表情包、俏皮话丝毫不影响作者把复杂的技术点讲清楚，讲透彻。

这一次，彻底弄懂 JavaScript 执行机制 - 掘金

chrome开发者工具各种骚技巧 - 掘金

趣文：编程语言伪简史 - OSCHINA - 中文开源技术交流社区

2.3 第一人称，故事开展

没人不爱听故事。

能把日常工作中碰到的难题，通过小故事的形式娓娓道来。

作者碰到问题了，读者跟着揪心，作者想到技术方案把问题解决了，读者也跟着高兴。

这类文章最考验作者的功底，但是效果拔群。

5秒到1秒，记一次效果“非常”显著的性能优化 - 掘金

记一次大厂的面试过程 - 掘金

2.4 逻辑下沉，技术深入

能把一个细分领域，讲全讲透，文章严肃规范，值得信赖。

文章内容高度可复用，看完文章，你也可以实现一模一样的技术能力。

方法论之所以被称之为方法论，正是因为可复制、可落地的特点。

手把手教你搭建一个无框架埋点体系 - 掘金最详尽的 JS 原型与原型链终极详解，没有「可能是」。（一） - 简书 - 掘金

线上Kafka突发rebalance异常，如何快速解决？

掌握 JS 高级编程基础 - Reflect Metadata

2.5 深入浅出，系列文章

系列文章往往让人忍不住追更，全文深入浅出。

跟随着作者的脚步，完整的学习掌握整体技术栈。

手摸手，带你用vue撸后台 系列一（基础篇） - 掘金

JavaScript深入系列15篇正式完结！ - 掘金

2.6 热点概念，前沿信息

人人都爱追热点，前沿信息第一手掌握。

让你成为前端界最靓的仔。

Web3.0来了，花呗借呗前端团队开源的Web图形引擎会成为元宇宙的技术支撑吗？ - 掘金

尤雨溪携手字节前端专家，畅聊 Vue 3.0 & 前端技术新趋势 - 掘金

3 怎么样去写一篇文章

知道什么是好文章之后，我们一起看看怎么写出一篇好的技术文章。

3.1 确定选题

确定选题非常关键，重点是思考『它是否能解决自己或他人最迫切的现实问题』，我们先看下有哪些题材来源。

3.1.1 题材来源

1）日常记录和总结

日常工作中，对遇到的问题、完成的项目及时的记录、总结，久而久之就自然积累了写作的题材。

2）深耕领域技术

在自己擅长的特地领域技术上，不断深耕，逐渐成为领域专家，并把阶段性的学习成果输出成一系列的文章。

3）源码走读分析

对当下热门框架、工具的源码进行分析、解读，沉淀为源码分析类的文章。

4）国内外新热文章

对国内外的新热技术进行尝鲜，分析利弊，并落地到实际的项目中，输出技术实践类文章。

5）读书分享

读完技术书籍后，加以总结，沉淀精髓，总结为文章，带领读者快速的了解该书的内容。

3.1.2 受众分析

不同的受众关注点存在差异，只有关注用户的需求，针对性的写作，才能写出口碑爆棚的好文章，所以首先要确定你的受众是谁？是领导，还是技术、产品，还是同一个技术通道的同事，不同的受众表述方式会有些不同。

对于大多数技术文章来说，常见的受众有：

1）相同技术类别： 有足够知识背景，适合使用专业术语深入探索某一个领域逻辑；

2）不同技术类别： 有一定知识背景，适合架构分享、项目总结类文章；

3）产品、运营：技术背景相对薄弱， 适合深入浅出，科普介绍技术的实现和目的；

结合自身题材来源、受众分析，最终确定一个自己擅长且有受众的选题，然后深挖用户痛点，写出对受众有价值的文章。

3.2 收集资料&素材

确认选题后首先要对题材有一定了解，根据不同题材的来源，收集对应的资料、素材，才能保证文章的高质量，这是写好一篇技术文章的基石。

通常我们可以通过以下几种方式来进行资料的收集工作：

1）平时知识储备： 平时读书笔记、项目记录，知乎 和 公众号相关文章的收藏、总结、思考等；

2） 请教该领域的专家，是否有推荐的书籍与资料，当前主题相关知识的关键要素有哪些，主要挑战有哪些；

3）善用搜索引擎，必要时阅读相关领域前沿学术论文期刊，以图获取最可靠专业的技术信息；

做好收集资料的目的在于：

1）保证文章的可靠度、专业性；

2）至少保证专业对齐甚至超出行业领先水平，以提供足够的价值；

3.3 确定大纲

通过材料收集、阅读之后，我们就可以开始确定文章大纲

3.3.1 梳理内容刚要

首先可以通过脑图来构建文章大致的结构，跟写代码，做技术框架是一个道理，比如：

文章《怎么把延时队列讲明白》通过脑图形式帮自己构建写作的框架。后面再通过内容的补充，读者阅读的时候也比较有结构化，便于理解。

3.3.2 拟定标题

确定文章内容结构后，我们就可以开始拟订标题，优秀的标题往往具有以下特点：

1）标题新颖吸引，引入注意，适合技术科普；

2）标题贴近生活，引起共鸣，适合技术实践；

3）标题权威专业，适合深度剖析；

而标题的拟定则可以遵循4U公式

1）Urgent 紧迫性，给读者一个立即点开的理由；比如，《你的成功在下班后8小时》如果把标题换成《30岁之前学什么，才能避免40岁失业？》从年龄的维度，给读者一种紧迫感

2）Unique 独特性，用全新的角度去描述一件事情；比如，《网易运维知识入门方法论》可以换成《2022年开年第一场 -- 网易运维知识方法论》。

3）Ultra-Specific 明确性，用明确的语言给读者带去可以确定的预期；比如，《2022年，前端最流行的10个Node框架》通过数字以及“最流行”明确告诉阅读者文章所讲的内容，让阅读者提前有心理预期。

4）Useful 实用性，暗示明确的益处，给读者带去价值；比如，《微信事件中心 - 高可靠、高可用的事务消息平台（附大会PPT下载）》在标题中加入“大会PPT下载”几个字之后，读者可以直观地感受到价值，可以拿到一手资料。

3.3.3 编写大纲（金字塔原理）

最后是拟订正式大纲，大纲之于文章，相当于栋梁之于宫舍，是起到支撑性作用的关键核心。

古人说：美人在骨不在皮。同样的，对于好的技术文章来说，优秀的大纲就是美丽的"骨相"。

而想要写出一个好的大纲，目前最经典的模式就是"金字塔原理"，层层递进，环环相扣，而践行"金字塔原则"的核心要素在于实现三个"上下"：

3.3.3.1 冠上履下

先声夺人：文章的开头就需要点明主题，让读者一目了然：

1）这篇文章主张什么观点；

2）通过这篇文章可以学习到哪些知识；

3）这篇文章所描述的内容解决了哪些问题；

4）这篇文章可以带来哪些附加价值；

文末总结：文章的结尾需要总结全文，归纳要素，升华主题，引人思考，加深读者的印象。

这里为大家提供字节前端团队的《手把手教你搭建一个无框架埋点体系》作为案例：

字节前端团队创作的《手把手教你搭建一个无框架埋点体系》文章截图

3.3.3.2 以上统下

有了好的开头和结尾，还需要对自己的核心观点进行梳理归纳。

首先需要归纳出一个核心论点，再将核心论点拆分成数个二级论点，每个二级论点又可以进一步细分，形成理论体系，环环相扣，以面覆盖点，以点连接线，把整个文章塑造成一个整体。

具体做法可以遵从MECE原则

MECE分析法也叫（枚举分析法），全称 Mutually Exclusive Collectively Exhaustive，中文意思是“相互独立，完全穷尽”：即对于一个重大的议题，能够做到不重叠、不遗漏的分类，而且能够藉此有效把握问题的核心，并解决问题的方法。

MECE原则有五种分类法。

1. 二分法， 是指可以按照对立方式分类，比如白天和黑夜
2. 过程法，是指按照事情发展的时间、流程、程序，对信息进行逐一的分类。
3. 要素法，是指把一个整体分成不同的构成部分，可以是从上到下，从外到内，从整体到局部。 比如一个小区包括几栋楼，一栋楼包括几层。
4. 公式法，可以按照公式设计的要素去分类，比如销售额=流量×转化率×客单价×复购率
5. 矩阵法，通过二维矩阵的方式来分类，比如时间管理中把你的工作分成以重要紧急、重要不紧急、不重要但紧急、不重要也不紧急。然后可以把它们填到4个象限当中去，这种分类方式就叫做矩阵法。

这里为大家提供树哥聊编程的《线上Kafka突发rebalance异常，如何快速解决？》作为案例：

树哥聊编程的《线上Kafka突发rebalance异常，如何快速解决？》文章截图

3.3.3.3 承上启下

有了好的头脑以及架构骨骼，我们还需要肌肉和关节使得肌体变得灵活通顺。

技术文章中论点与论点之间，段落与段落之间，需要有合理的过渡，避免出现逻辑断层或者表达断层，造成读者的不适。

古人说：文章本天成，妙手偶得之，所描写就是好文章的特点之一便是具有自然通顺的起承转折，像是天然生成一般令人舒适神往。

这里为大家提供广顾dun的《最详尽的 JS 原型与原型链终极详解，没有「可能是」》作为案例：

广顾dun的《最详尽的 JS 原型与原型链终极详解，没有「可能是」》文章截图

3.4 写作流程

大纲完成之后，如果快速形成文章呢？好的技术文章一定是有一套完整方法论的体系产品，这意味着我们可以通过标准化的流程，降低我们写作的难度和门槛。

首先第一步是『写草稿』，先把『字』写出来，这一步应该不难，然后不断修改完善：

优秀的文章都是经过不断修改，千锤百炼，从草稿到最终稿要经历无数次审稿、重新编辑输出最终定稿，过程中自身至少阅读20遍以上，确保行文流畅。

4 写作技巧

4.1 标题技巧

酒香也怕巷子深，好文章也要搭配好标题才能更快更广的传播，下面介绍几种起标题的技巧：

4.1.1 强调干货型

从标题上就向读者灌输这篇文章的高质量，例如：《学习XXX，看这一篇就足够了》、《全网最全的XXX，没有之一》。

4.1.2 直戳痛点型

找到当前大部分人面临的问题，直戳痛点，例如：《用了这么多次，为什么你还是记不住正则表达式》、《工作三年，为什么你只会写CRUD代码》。

4.1.3 蹭热点型

找到当前新闻热点，以该热点为背景展开，例如：《从艳照门引发的安全存储思考》、《吴亦凡事件背后的微博优化之路》。

4.1.4 悬念型

设置一个悬念，引发读者阅读，例如：《首屏耗时从2秒到0.5秒，我是怎么做到的》、《支持千万人参与的秒杀活动，背后核心技术竟是...》。

4.1.5 反差型

标题形成一个强烈反差，吸引读者眼球，例如：《10年资深前端，却被这个正则难住了》。

4.1.6 人群标签型

带人群标签，可以快速的吸引到对应人群，例如：《写给TS小白的入门教程》、《给PHP初学者的忠告》。

4.1.7 故意否定型

故意否定读者，激发读者的胜负欲，例如《你真的懂XXX吗》、《你不知道的XXX内幕》。

4.2 写作技巧

4.2.1 从『写』开始

就像『出来混』最重要的是『出来』，『写文章』也是，最重要的是开始『写』，只要你提笔开始写，用自己熟悉的方式，像聊天一样写作，发现并没那么难，期间遇到问题再解决，就能逐步提升写作技巧。

4.2.2 模仿

模仿是我们婴儿时的学习方式，用在其他学习场景一样非常有效，在写文章的领域，可以从模仿你喜欢的作者、模仿你喜欢的写作风格开始，这是起步最快的方法，很多大V都是从模仿开始写作的。

4.2.3 滑梯理论

滑梯理伦是指：读了第一句之后，就想接着读第二句，读了第二句之后，就想接着读第三句，然后像顺着梯子往下滑一样，一直滑到底。

我们必须想办法让读者看到后，眼睛就无法离开，然后让他的目光自然往下“滑”。

坚持这样的刻意练习，我们文章的可读性就会提升很大一块。

4.2.4 故事开头或痛点吸引

我们大脑里其实同时住着“理性”和“感性”两个小人。

其中“理性小人”很高级，但“感性小人”更强大，所以绝大多数时候，我们的行为都由感性所主导，包括接受信息。

所以我可以先从大脑喜欢轻松有趣的故事开始，或者从能引起我们情感的痛点开始，先引起对方情绪上的关注，然后再把想说的道理通过对方的“情绪小人”转交给“理性小人”。

4.2.5 打磨意识

好的文章都不是一戳而就的，需要不断打磨，自己反而阅读、修改，直到整体行文流畅为止，在请人帮忙审稿，提出改进建议，在继续修改完善，直到满意为止。

4.2.6 一图胜千言

1）在文章中增加架构图，推荐使用  excalidraw 工具，其手绘风格会比较生动，比如

2）增加图表，增强可信度，比如狼叔在NodeJs的使用年度报告中，就列举了大量的数据图表，说明数据来源的真实性，支撑了文章总结的观点

3）插入漫画或者表情包，增加趣味性

漫画制作工具

什么是MD5（图）

表情包制作工具

JS运行机制（图）

4.3 工具分享

4.3.1 markdown工具

写文章时，经常涉及到多平台同时发布的问题，例如公司内网、微信公众号、掘金等等。

此时markdown就是我们的跨平台发布的不二法门，这里同样推荐两款markdown工具：typora、markdownnice。

4.3.2 绘图工具

人类的天性让我们对图形化的东西更感兴趣，好的文章少不了好的图例，这里附录了一些常用的绘图工具：draw.io、processon、excalidraw。

4.3.3 源码处理

技术文章往往离不开挂代码示意，美观的代码格式也很重要。

有意的降低目标用户的阅读理解成本，为阅读用户营造一种被认真对待的代码观感同样十分重要。

这里推荐源码处理工具：carbon。

4.3.4 文章封面

相信大家平时都有被抖音 b站上一个有趣的封面所吸引而点击观看的情况，字不如图，好的封面也能显著提高文章的点击传播效率。

这里推荐两种文章封面生成工具：pixabay、pexels。

4.4 写作规范

4.4.1 标题

标题分为四级。

1、一级标题：文章的标题；

2、二级标题：文章主要部分的大标题；

3、三级标题：二级标题下面一级的小标题；

4、四级标题：三级标题下面某一方面的小标题；

原则：

1、一级标题下，不能直接出现三级标题；

2、标题要避免孤立编号（即同级标题只有一个）；

3、下级标题不重复上一级标题的名字；

4、谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节；

4.4.2 文本

4.4.2.1 字间距

全角中文字符与半角英文字符之间，应有一个半角空格

全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。

英文单位若不翻译，单位前的阿拉伯数字与单位符号之间，应留出适当的空隙

半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。

4.4.2.2 句子

避免使用长句。

尽量使用简单句和并列句，避免使用复合句。

避免使用双重否定句。

4.4.3 段落

原则:

1、一个段落只能有一个主题，或一个中心句子；

2、段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为核心句服务；

3、一个段落的长度不能超过七行，最佳段落长度小于等于四行；

4、段落的句子语气要使用陈述和肯定语气，避免使用感叹语气；

5、段落之间使用一个空行隔开；

6、段落开头不要留出空白字符；

4.4.4 数值

阿拉伯数字一律使用半角形式，不得使用全角形式。

数值为千位以上，应添加千分号（半角逗号）。

货币应为阿拉伯数字，并在数字前写出货币符号，或在数字后写出货币中文名称。

更多请参考：中文技术文档的写作规范 - 阮一峰的网络日志

4.5 写作案例分享

下面分享几个典型文章类型的基本写法，供大家参考

4.5.1 技术介绍型文章

这一类文章，往往是是偏向于技术科普，如《web3是互联网的未来？》、《VR、AR、MR、XR分不清楚》等。

它们的共同特点是将新技术讲清楚，让读者对文章描述的技术内容有全面的了解，一般包含以下内容：

1）新技术产生背景

一个新技术往往不会凭空出现，一般伴随着一些历史进程的推进，如 WEB3 的出现并不是仅仅是资本的追捧，其诞生的目的是目标是无服务器去中心化的互联网，让用户自己掌握自己的身份数据。这里的技术背景可以从多角度来分析，业务发展述求、周边技术的更新迭代等都是其影响因素。

2）与现有技术对比

新技术往往会参考了一些现有技术的缺点进行改进，这里可以重点将其优缺点通过图表的方式列出，更直观的让用户对新技术有更全面的了解。

WEB3和WEB1、WEB2对比（图）

3）举例说明新技术的特点

        可以先归类列出其特点，并对其特点进行一一展开，通过剖析技术的底层实现来展开讲解该技术的特别之处，如WEB3的核心组件智能合约。

WEB3的核心组件（图）

4）介绍新技术的实践

     这里偏向于新技术的具体实践，如果是大的技术方向的话，可以列举出他们的应用场景的落地，如WEB3的NFT，XR领域的Pokemon Go；如果是某一个技术范围里的新技术栈，如前端领域的Vite，这里可以结合demo代码给出一些演示示例，还可以通过对比和老技术的数据差异，进一步突出新技术的特点。

5）总结其特点，并阐述其未来走向

     这里主要是总结下新技术的特点和实践，可以结合技术走向和作者观点对其未来给予展望。

示例文章

VR、AR、MR、XR分不清楚

最被广泛认可的 Web3 科普

4.2.2 问题定位型文章

该类文章一般都是记录一次问题的定位。一般这种文章都是以第一人称的角度来详细详阐述解决问题的全过程。让遇到相同问题的读者有切身感受，让没有遇到这个问题的读者，也能顺着文章的递进进行一次知识的洗礼。

1）问题介绍

这里主要是阐述当前问题产生的背景或者是详细的问题介绍，在什么情况下发生了什么，例如测试同学在测试过程中发现了点击多选框的选项会造成整个网页的卡顿、或者是当前项目存在请求时间不稳定，出现经常超时的情况。主要目的是让读者更加清晰的了解到问题产生的所处环境。

2）针对该问题的常见原因分析，给出猜想

给出出现该问题的一些常见原因。比如网站打开速度慢是因为：网络问题，前端资源过大，后台接口慢，或者是网关慢。并且结合场景还原给出猜想。

 网页内测溢出原因猜想（图）

3）问题分析及排查过程

既然是问题定位型文章，这里一定要有详细的问题排查过程。一般是对引起该问题的原因逐一验证，以及在进行修复问题的回滚验证是否猜想。在得到引起该问题的真正原因后，再给出详细的解决方法。

4）总结

最后就是对文章做总结，总结可以是解析该类问题的一些其他思路畅想，或者总结一些定位该类问题通用的方法论，以便读者也在解决该类问题能够尽快的去处理。

示例文章：

记一次网页内存溢出分析及解决实践

5秒到1秒，记一次效果“非常”显著的性能优化

5 总结

本文从为什么要写文章入手，介绍写文章对作者与读者的好处，带领读者分析了几种典型的好文章，然后从写作流程和写作技巧的角度为读者讲解了写好一篇文章的每个环节应该注意什么、有什么技巧与工具。

不过最重要的还是文章能否为他人创造价值，能否解决他人最迫切的现实问题

最后感谢您抽时间阅读，期望本文能帮助您在写作上有所进步，也欢迎大家留言交流写作相关话题。

6 文章参考

中文技术文档的写作规范

写了 200 多篇文章后，我总结的写作心得

关于写作，这是我目前能想到最全的

如何逻辑思考，清晰表达？《金字塔原理》和本文值得一读！- 知乎