前言

我们为什么要写技术文章呢？在工作中如何沉淀出技术文章呢？如何写好一篇技术文章呢？相信通过这篇文章你可以得到答案。那么我们开始吧。

写作前的事情

1. 写作价值

1.1. 传递和分享技术

前人栽树，后人乘凉。 在日常开发和运维工作中，开发人员往往会借助大量的手段学习、分析、解决问题，比如：官方文档、开源社区、技术博客和公司内部论坛等。

通过写作技术文档、技术文章，可以在技术圈子传递和分享自己对一个技术的 认知 和 经验总结，接受反馈、相互学习，加强对技术的探讨和升华。通过他人技术文章解决问题的同时，我们也应该学会 反哺。

1.2. 打造个人影响力

一篇实用的技术原创文章，可以为自己带来大量的读者，可以发掘和提高个人包含技术在内的能力，大幅提升个人的 影响力。

1. 写作好的技术文章可以提高自己在 行业、公司内部 的影响力，为行业或公司 沉淀知识体系。
2. 持续输出高质量的文章可以 打造个人流量，帮助他人的同时 获取流量 和 知识付费变现。

1.3. 提高个人总结能力

写作对个人的专业水平和综合能力是有一定的门槛的。正所谓技多不压身，除了基本的编程开发能力，开发人员还应该具备一些其他技能：

• 技术学习能力：擅于学习新的技术，总结规律、形成自己的学习体系和知识库，对任何新技术都能快速上手、举一反三和融会贯通。
• 文档沉淀能力：学而时习之，由于技术和知识体系过于庞大，需要定期进行总结和归纳，形成自己的知识备忘录，加深对技术的理解。
• 问题排查能力：将线上疑难杂症的分析解决能力以文档、博客的方式总结，方便后续遇到同类问题时能够快速分析、定位和解决。

2. 写作障碍

2.1. 从0到1：从没写过到写过

万事开头难，技术写作也是一样，通常迈出第一步是最难的，这个阶段的核心是 突破自己内心的障碍。这时的障碍主要来自两方面：

• 个人内容方面：担心自己的文章 描述有误、内容不足 以及 深度不够。
• 他人观点方面：担心比自己厉害的人笑话自己写的 文章不好，无法解答他人提出的 疑问。

有这两方面担心很正常，当然这两方面的担心其实也都好解决。

• 个人内容问题：

明确定位文章的 面向群体，面向初级、中级、高级、TL 还是技术总监，内容高度是有很大区别的。不同岗位、不同职级的人本身对 文章层次 的需求相差甚大，并不是高度越高就越好。

• 他人观点问题

一定有很多比我们厉害的人，那么这些人会带着什么心态去看这些文章呢？

首先可以明确不是带着批判的心态，其次他们可能也希望通过文章去补充自己，看看是否有新观念、新想法的出现。即使不符合他们的胃口，比如讲的内容自己可能做得更好，他们会很快关闭去看其他的，而不是继续浪费时间。当然，还有一种可能，他们可能并 不会打开。总之，这方面也没有什么可顾虑的。

2.2. 从1到N：从不想写到主动写

迈出第一步之后，接下来这个阶段的核心是 持续积累、总结 和 输出。

不积跬步无以至千里。要写出 高质量 的文章，需要不断地 积累素材 和 总结经验，最后通过文字表达出来。先说下积累和总结，这个分 积累素材 和 系统总结：

• 积累素材

在日常学习和工作中，要养成 记录随笔 的习惯，随时记录一下自己对技术的理解和思考，也包括工作实践中的 踩坑避雷 的经验总结。这个过程不限于 阅读、收藏 他人的好文章、提炼 出核心的 技术知识点，并对素材和知识点进行 标记 和 归类。

• 系统总结

当某项技术的收藏和记录 知识素材 积累到一定程度时，你对技术的 理解 和 认知 也会达到一定的 广度 和 深度。当你在工作中 应用到 这项技术，将理论基础和实践中的 技术方案、技术调优 和 数据支撑 相结合，融入工程化实践和自己的观点，最终将知识 结构化 和 文档化，就形成了一篇 高质量 的文章。

3. 写作内容

在日常工作中哪些内容可以沉淀为技术文章，我们得先清楚 哪些内容 是可以产出技术文章。

3.1. 线上故障和解决经验

你遇到过的线上技术问题和难题，一般是某个具体的技术点（bug、性能、生产事故等），经过你的 分析、排查 和 处理，问题得到了 有效解决，解决后你又 系统性地 学习和研究了相关技术知识，即可总结为一篇文章。

3.2. 设计方案和工具介绍

你在工作中为解决某个 业务问题，通过 分析、调研 和 验证 等环节，产出的 设计方案，及其使用到的相关 工具、框架 或 组件 等，可总结为一篇文章。

3.3. 新技术和新趋势介绍

你关注的行业发展中出现的 新技术、新趋势，能提高解决问题的 效率、带来更好的 实践 或能够有效突破现有技术的 瓶颈 等，可总结为一篇文章。

3.4. 项目遇到的挑战和解决方案

你参与过的某个项目，为了 按时高质量 的交付，遇到的一些挑战（问题、风险等），可以是 技术方面 的挑战，也可以是 沟通协作 的挑战，或者是 工作模式 的挑战，都可以总结出经验和教训。

3.5. 好用的开发工具和使用技巧

你在写代码、调试、测试和运维等阶段，发现了好用的 工具、技巧 或 规范，能够提高 工作效率、代码质量 等，也可总结为一篇文章。

3.6. 编程语言和框架的实践经验

你学习的 编程语言、技术框架 的学习笔记（梳理、总结 等）、实践经验（Demo 代码、实际应用），可总结为一篇文章。

4. 写作途径

好记性不如烂笔头，写作不是一个作者的专职工作，日常工作和学习有很多锻炼的方式，对于程序员来说有哪些方式呢？

4.1. 写代码注释

在日常开发工作中，写好代码注释也是一种好的手段。如果你的代码写得足够优秀，是不需要过多注释的，注释是对代码的一种理解的增强。

对于 复杂业务场景、公共代码库 以及 晦涩难懂 的代码，清晰的注释可以帮助其他开发人员快速理解 业务上下文 和 代码逻辑。

什么是好的注释：

1. 注释应当 简短、精炼 和 清晰，避免长篇大论的说明论述。
2. 告诉大家你  “为什么”  写这个注释，而不是 告诉大家这段代码  “是什么” ！ “是什么”  应该交给代码本身去解释，这个最为关键。
3. 注释有 时效性，持续维护 你的注释，也就是记得及时更新，与当下 代码语境 匹配。

4.2. 回答技术问题

1. 回复简书、掘金、知乎、51CTO、CSDN、博客园和思否等平台上他人提出的问题。
2. 在 Github、Stack Overflow、官方技术平台等平台提出、回答问题。
3. 在公司内部技术论坛、其他团队的技术文档下提出问题。
4. 在内部代码检视时和 Pull Request 时给予合理的评论。

4.3. 写技术博客

1. 在微信公众号、简书、掘金、知乎、51CTO、CSDN 和博客园等平台发表技术文章。
2. 在 InfoQ、51CTO、阿里开发社区等官方技术平台刊登杂志、技术博客。
3. 定制自己的技术博客网站，通过内容品质、站点运营推广自己的技术文章。
4. 开通个人知识星球圈子，将个人技术文章进行沉淀、整理和归档。
5. 在公司内部技术论坛、技术博客发表技术博客，包含内部技术和开源分享。

4.4. 写技术文档

1. 利用 Gitbook、Docsify、VuePress 和语雀对某个技术领域进行长期的知识沉淀。
2. 在公司内部 Confluence Wiki、WPS 文档和公司代码仓库编写技术文档。

4.5. 写技术书籍

对某个技术领域有了深入和系统的学习、理解和思考，有了 成系列 的技术文档、技术博客以后，就可以考虑出版技术书籍的可能。

如果需要出版技术书籍，要先了解市面上同类书籍的内容，确定出版书籍 针对的方向、侧重点、独特性。主要的出版社如下：

1. 图灵出版社
2. 机械工业出版社
3. 人民邮电出版社
4. 电子工业出版社
5. 清华大学出版社

5. 写作工具

俗话说得好，工慾善其事，必先利其器。最后分享一下不错的文章写作工具。

5.1. 画图工具

ProcessOn

ProcessOn 是一款专业强大的作图工具，支持 多人实时在线协作，可以用于在线绘制 流程图、思维导图、UI原型图、UML图、网络拓扑图、组织结构图 等。ProcessOn 只能支持 9 张免费在线图片存储，支持多种格式的图片文件 导入导出，能够兼容不同的操作系统，不管是 Mac 还是 Windows，一个 浏览器 就可以完成画图工作。

• 价值链图（EVC）
• 常规流程图（Flowchart）
• 事件过程链图（EPC）
• BPMN2.0 图
• Venn 维恩图
• Org 组织结构图
• iOS 线框图
• UI 页面原型设计图
• UML 统一建模语言
• 高端时序图

更强大的功能，支持多标准的格式交换：

• 支持将 Visio 图转换成 ProcessOn 文件
• 支持将 BPMN2.0 文件转换成 ProcessOn 文件
• 支持将 ProcessOn 的 BPMN 图导出成 BPMN 格式文件
• 支持将 ProcessOn 的图导出成开放格式的 pos 元数据文件等

Draw.io

Draw.io 是一个很好用的 免费流程图 绘制工具。

你可以利用它绘制一系列的图表、图示或图形，包括 流程图、UML类图、组织结构图、泳道图、E-R图、文氏图 等，适用于商务、工程、电气、网络设计、软件设计等诸多领域的专业绘图。它致力于成为 完全开源、免费、并且高质量的绘图软件。

软件内置了相当丰富的绘图资源，包括各类形状、图标、连接器、模板，能满足绝大大多数的绘图需求，还可以导入第三方图标资源满足更多需求，完全可以取代微软 Visio 等流程图软件。

Excalidraw

Excalidraw 是一款非常轻量的 在线白板 工具，可以直接在浏览器打开，轻松绘制具有 手绘风格 的图形。Excalidraw 基于 Markdown 语法实现绘图功能，不仅 简洁轻量，还可以和 Markdown 编辑器的工具集成，实现各种特色功能。

与 Visio 绘图相比，在 Obsidian 工具中使用 Excalidraw 绘图的优势体现在：

• 基于 Markdown 语法创建绘图，源文件简洁轻量。
• 图形源文件完美嵌入 Obsidian 笔记，支持随时编辑修改。
• 灵活的个性化设置，实现创建、编辑、管理、分享图片一气呵成。
• 手绘风格清新优雅。

5.1. 图片平台

好的文章需要好的封面，有条件的可以自己画，也可以用一些工具来生成，比如 创客贴、稿定设计 等，也可以是任意的图片。

创客贴

创客贴 是一款简单易用的 线上图形设计神器，功能十分强大，涵盖了新媒体营销、公众号运营、广告印刷、工作文档、电商、生活等多个场景。

稿定设计

稿定设计 是一款专为电商运营者、新媒体运营人员和作图爱好者打造的在线智能化平面设计工具。通过 简单拖拽 操作，一分钟即可轻松搞定不同场景不同尺寸的各种设计。

写作中的事情

1. 创建大纲

组织文章的 结构 和 内容，其中的 结构 是指文章的 结构组织方式，内容 更多的是指 内容大纲。

1.1. 梳理写作结构

有了好的内容，还要注意文章的结构。关于结构，有一本书叫 《金字塔原理》。金字塔原理教导我们在写作、表达的时候，要构建 清晰的结构。

对于一篇文章来说，金字塔的顶点是 中心论点，即通常就是文章的标题。围绕着这个 中心论点，我们可以用 多个观点 去支撑中心论点。如果表达的内容很多，观点还可以进一步 往下细分。形成一个 以上统下、逻辑递进 的金字塔结构。

通过这种形式写出的文章，就会显得逻辑清晰，结构紧凑。

对于技术文章来说，可以考虑使用 3W2H模型 来 构建结构。比如要写一篇关于 抽象能力 的文章，就可以通过以下角度去说：

1. What：什么是抽象。
2. Why：抽象为什么重要。
3. How：如何进行抽象.
4. Where：抽象可以用在什么地方。
5. How much：抽象到什么程度。

格外提一点，文章的 开头 和 结尾 要同样是比较重要的，不要忽视。

• 要有引入入胜的开头

概述文章的主题，能够做到吸引读者的注意力，一般可以通过提出问题、讲述一个引人注目的事实或相关的故事。

• 在文章最后要有总结

主要是总结文章的主要观点，重申你的观点，提供进一步的建议和行动指南。

1.2. 选择组织结构

需要根据文章的主题和目的选择 合适 的组织结构，以便让读者更容易理解。常见的技术文章组织结构如下：

问题解决结构

按照 一个 或 多个问题 来组织，然后通过提供 解决方案 来回答这些问题。这种结构的文章通常适用于 技术教程、解决问题 的指南和操作说明等。

步骤性结构

按照一系列步骤或操作来组织，以便读者能够 跟随步骤 完成任务或操作。这种结构的文章通常适用于 技术教程、操作说明 和 编程教程 等。

分析性结构

按照一系列 概念、理论、方法 或 技术 进行分析和解释，以便读者能够更好地理解 技术原理 和 应用场景。这种结构的文章通常适用于 技术分析、技术评估和比较 等。

项目式结构

按照一个完整的项目或任务来组织，以便读者能够了解整个项目的 实现过程 和 技术细节。这种结构的文章通常适用于 项目开发 和 技术方案实现 的介绍。

说明性结构

按照一系列 技术概念、术语 和 技能 等进行解释和说明，以便读者能够更好地理解 技术知识 和 应用场景。这种结构的文章通常适用于 技术介绍 和 技术文档 等。

1.3. 确定内容大纲

内容大纲是根据文章的组织结构、主题和目标确定的，以下是一些建议：

列出主干部分和子部分

根据主题和目标确定文章的 主干部分，及其 子部分，帮助你理清 内容结构 和 思路，确保能够覆盖到主题的各方面。

确定各部分的主要内容

对于每个主要部分和子部分，进一步 拆解，确认它们的 主要 和 重点内容。

编排各部分的逻辑顺序

根据文章的主题和目标用户，采用适合的顺序 组织 各个部分，使其有更好的可读性和连贯性。

备注注释和细节

在内容大纲中，结合收集到的信息和文章思路，添加一些重点的 注释、细节，以便在写文章时，不会遗留一些重要的细节和思路。

2. 组织文章

按照文章的提纲，开始写文章。为了让读者易读、易懂，要做到 清晰地组织文章，以下是一些建议。

2.1. 语言简洁明了

• 不要使用复杂的语法、词汇、行话，尽量使用 短句，一句话要控制在 40字 以内。
• 尽量不要用 长段落，大约 3~5行 就需要另起一段了。

2.2. 使用段落和分层

• 多采用 标题 和 小标题，凸显出内容层次和主题聚焦度。
• 每个标题内采用 段落，每个段落的 开头放主题句。
• 段落内 采用 迭进顺序，可按照 时间顺序、逻辑顺序、重要性顺序 等
• 多采用 列表，可以是有序列表或无序列表，让 逻辑条理更加清晰。

2.3. 使用辅助图表和示例

在阐明观点、概念的同时，辅助图表、插图、数据、示例（实际的案例、含注释的代码等）更加 直观吸睛，让人觉得更有 说服力。其中可视化相关的 图表、插图 和 表格 等是尤其高效和受欢迎的。

2.4. 删除不必要的内容

在保证内容完整性的基础上，内容 越简炼越好。写文章和复审时，要有意识地只保留与 主题相关 的信息，如不使用 不必要 的形容词、副词等，专心于核心内容，不做额外修饰。

2.5. 避免重复词汇

总是 重复 的词汇、观点，会让读者感到 低效 和 枯燥，因此需要避免，可使用一些 同义词替换。

2.6. 注重细节和准确性

• 如果有引用，要有 参考资料 和 链接（参考资料最好有一定的权威性和准确性）。
• 不要有 错别字，越是细节越要注意准确性，这样会让读者感觉到专业、精品。
• 如果是 中文写作，请务必用 中文标点。

2.7. 注意排版和格式

• 使用合适的 字体、字号 和 间距。
• 文章中的 重点观点 和 关键词 可以着重 加粗
• 注意分段讲解，注意标题、段落和层次结构。
• 标准、易阅读 的示例代码、引用、图片的 表达样式。
• 为了减少在调整格式上花费大量的时间，推荐采用 Markdown 文档。

2.8. 保证逻辑环环相扣

环环相扣 是指内容不要一下子全讲完，要留下一个 信息缺口 和 层层递进，承上启下 引出下一部分内容，直到文章最后再形成 完整闭环。 从标题开始就要留信息缺口，引起好奇心，吸引读者继续往下读。

总结

到此，文章即将结束，让我们回顾下文章开头提到的三个问题：

• 我们为什么要写技术文章呢？我们认识到了写技术文章的好处。
• 在工作中如何沉淀出技术文章呢？我们知道了可以写什么、什么时间可以写。
• 如何写好一篇技术文章呢？我们知道了具体如何写好一篇文章，里面有一些关键点、细节需要注意。

相信你或多或少地得到了一些答案。本文只是做了一个引导，实践出真知。要写好一篇技术文章，需持续不断地 强化练习，才能 下笔如有神。