如何从 0 到 1 写好技术文章

如何从 0 到 1 写好技术文章

引用

CSDN

1.

https://blog.csdn.net/m0_60961651/article/details/132707430

写技术文章是程序员必备的技能之一，但很多人在动笔时都会遇到各种困难。本文将从五个方面详细讲解如何写出高质量的技术文章：确定目标读者、理顺写作思路、创作吸引人的标题、提升表达能力以及持续优化体验。

Lv 1 下笔前思考：你是否了解目标读者？

“If I were given one hour to save the planet, I would spend 59 minutes defining the problem and one minute resolving it.” — Albert Einstein

如何确定自己的技术文章是否能帮到目标读者？

• 如果你过去或最近从事的所有项目中，遇到一个难题，开始不确定如何处理和解决，但最终通过某种方法解决了 -> 撰写博客、分享知识的绝佳机会。
• 10 次中有 9 次，你遇到了问题，其他人也遇到了 -> 为什么不写成博客/文章？

明确写技术文章的目的？

• 介绍技术原理/产品？
• 帮助别人解决问题？
• 爱好、分享、自我提升？
• 知识变现?

技术文章的目标读者通常都是对你介绍的内容有兴趣的人（这些人群最有可能阅读你的文章，你需要满足他们需求来提供有用内容）

写给哪些人看？

• 技术小白、非行业内人员 -> 不能上来就整技术原理，并且需要通俗易懂
• 开发 -> 技术原理直接上
• 如果你的文章是为了让所有人都轻松得掌握某个概念 -> 语言越简单越好
• 例如如果你的读者大多数都是 00 后了 -> 使用社交媒体的入门文章对他们来说就没啥用了

如何更好地了解你的读者？

• 通过问卷等方式调研你的内容是否能真正地给他们提供帮助。比如他们关注哪类问题？经常出现哪些问题或疑虑？
• 查看他们在内容平台 follow 了哪些博主，以及那些博主都发布了什么内容
• 关注文章发布平台的数据看板
• 你的读者可能是在喝咖啡的间歇、或者吃完午饭午休前看文章的 -> 他们都试图在短时间内快速掌握一些内容/获得一些知识 -> 文章不能记流水账、太冗长

Lv 2 理顺写作思路：运用架构和逻辑思维

文章如同软件产品，也有架构和逻辑。好的技术文章一定具备清晰的结构和逻辑。

（大结构）列举一般技术文章的结构：

• 介绍项目
• 项目背景
• 自己在项目中的职责和完成度
• 使用技术和技术创新点
• 印象深刻的困难点
• 对比业界普遍的方案，整理自己方案的优势
• 介绍技术知识点
• 自己运用知识点的总结，总结时需要注重遇到的问题和解决思路、方案
• 知识点的深入学习，注重周边知识点，最好是能和原先的知识点联系起来
• 技术的广泛应用，学习技术需要它用在哪里，最好多了解一下技术的应用场景
• 问题总结
• 问题描述
• 核心原因
• 解决步骤 注：如果有常见的但是错误的解决方式，可以写出以方便他人参考。
• 总结
• 参考文献
• 编码技巧总结
• 应用场景
• 传统解决方案
• 存在问题
• 新的解决方案
• 优缺点
• 参考文献

（小结构）文章的结构化表达

• 主题先行
• 使用无序列表
• 归纳分组
• 逻辑递进
• 等等

要有清晰的叙事结构，不同的技术类文章也有不同的套路

• 技术细节型（侧重于解决某个具体问题，例如：如何解决某个 bug、如何使用某个具体的技术点、如何实现一个功能等） -> 使用 线性叙事，逐步递进（可以尝试模拟读者视角，设置一条主线，让读者跟着主线向前推进）
• 规划、总结、一整套技术方案 -> 使用 结构化叙事，层层展开（可使用总-分结构）

Lv 3 题好一半文：如何写好标题？

为什么要写好标题？

• 什么是好的标题？在措辞上，一个好标题一定是精简凝练的，能一下子抓住读者的注意力。有学术研究显示，标题简短的文章浏览量大于标题冗长的文章，同时也更容易被引用。此外，在内容上，好的标题一定是准确清晰的，能帮助读者快速了解到文档的主要内容，从而判断是否要打开你的文档。
• 标题是你文章的“门面”。好标题能让读者一眼了解到文章内容&主旨、引起读者兴趣，提高阅读量。

好标题一览/什么是好标题

• 用数字吸引眼球： 《 XXX 开源了 14 个核心技术，你了解哪些？》、《5 分钟带你通过 Javascript 了解人工智能的基本原理》
• 引发好奇心： 《数据分析在生活中的应用- 女人的衣柜里为什么总是少一件衣服》
• 大厂背书：《 字节跳动开源 Go HTTP 框架 Hertz 设计实践》《2021，字节最值得关注的 10 个开源项目》《求职特训营火热来袭 阿里大咖教你制作专业简历》
• 简明扼要、一眼秒懂主题： 《Apache Dubbo 出现严重漏洞，华为云 WAF 可提供防护》
• 瞄准受众、卖点明确： 《Hadoop 3.0 时代，怎么能不懂 EC 纠删码技术？| 个推技术实践》

如何写好技术文章标题

• 标题设计可以遵循SPA原则：
• 简明扼要（Simple） 标题不宜过长（建议控制在10个中文字以内），只保留核心关键字。
• 利益相关（Profit） 利益指的是标题要体现目标读者所关注的内容，即读者切实感兴趣的点。
• 准确客观（Accurate） 不宜过多表达主观情绪，在字数有限的情况下概括出全文核心本质，而概括全文便是运用了结构化思维中的“以上统下”。
• 思考：
• 要介绍的技术/产品的功能/特点/卖点？是否有核心优势、竞争力？
• 能给读者带去什么好处？
• 可能要根据不同的文章类型来判断用什么样的方法。
• 明确受众
• 蹭大厂/大佬的名字 《来自 Google 的 xxx》
• 好奇心 《TW 写好技术文档的诀窍都有什么？》

如何避免坏的标题

• 同质化标题
• 标题党
• 题不对文
• 过于宽泛

一些可以参考的标题模板

• 根据 Conductor 的研究：
• 36% 的人更喜欢带有数字的标题
• 21% 的人喜欢指明目标读者的标题
• 17% 的人希望标题包含“如何”
  公式 说明 例子
  XXX，你需要的唯一指南 向读者保证，他们可以从你的文章中找到有关某个主题的所有最重要信息 如何使用 Canva：创建视觉内容的 8 步指南
  带有数字的标题 给了读者一个预期：你的文章长度以及可以学到多少新东西 你可以用 XXX 种方式实现 XXXX
  “如何”标题 如何是一个常见的“触发词”，一般我们在搜索引擎上找内容都是以“如何”开头的。另外还有“怎么样”。另外，该标题承诺了会教给读者一些技能 如何写好技术文档？如何在不买粉的情况下在抖音上获得更多赞？

文后作业/改进案例

作业 1

• Step 1: Android 和 iOS（要介绍什么？操作系统？）
• Step 2: Android 比 iOS 好吗？（更突出了文章内容、主旨）
• Step 3: Android 比 iOS 更好的 12 个原因。（给了读者一个预期，文章有多长、会介绍多少内容）
• Step 4: Android 比 iOS 更好？——不该购买 iPad 的 12 个理由。(略带挑衅、但是足够引发你的好奇心)

作业 2

• 技术写作常见错误（很普通、一搜搜出一大把、但是不够吸引眼球）
• 请停止再犯这 15 种技术写作常见错误（似乎好一些了，but...）
• 专业技术文档工程师会避免的 15 种技术写作常见错误

Lv 4 如何提升表达 ：极简写作

“Anybody can have ideas–the difficulty is to express them without squandering a quire of paper on an idea that ought to be reduced to one glittering paragraph.” — Mark Twain

Part Ⅰ 为何要遵循极简写作

• 回顾你看过的技术文章，你更关注作者的写作风格和行文方式？还是文章中那些简洁易消化的信息？
• 多数人看技术文章带着明确的目的 —— 查找有用的信息。
• 如果文章简洁易读，那么你的读者就会觉得你没有在浪费他们的时间并在提供对他们有用的资源。

Part Ⅱ 对极简写作的理解误区

非单纯省字，而是简化读者 消化信息所需要花费的成本。

Part Ⅲ 如何用极简的方式来减少读者的理解成本

Tip 1：将大段落拆成大部分或系列文章

Tip 2：使用类比和例子

类比有助于帮助理解复杂问题、启发人们跳出既有框架思考、帮助讲好故事。

例子： SAP Leonardo 是 SAP 的一款全新的数字创新系统。……

改进： SAP Leonardo 并非一款现成的“产品”。它不像是在超市里买的现成的蛋糕；而是帮助你在自己的厨房里学习如何以工业化规模来做蛋糕。并且，在课程开始前，你要跟糕点师傅合作，弄清楚你要做啥样的蛋糕，是生日蛋糕？还是纸杯蛋糕？

蛋糕做得好不好要由食客来评价，糕点师傅会告诉你如何了解潜在的食客，以及他们真正想吃的是什么。当一切都有定论，糕点师傅就会提供预选的、恰好份量的“原料”给你，比如如物联网、数据分析、机器学习。

Tip 3：便于阅读的格式（留白、缩进）

Tip 4：使用轻松幽默/富有表现力的语言

Tip 5：分离“数字”和“解释”

真实可靠的数字/数据可让文章更真实。不过当你向读者展示大量数据时，可能会削弱他们的理解力，让文章变得不那么好读。因为人们阅读文章时，大脑进入的是“故事模式 —— 使用基于语言的大脑来阅读和理解内容。当大脑处理数字时，必须切换到“数据模式”才能理解信息。通常文字夹杂数字时，会出现两类阅读情形：

• 略过数字。
• 读者停下来仔细阅读，来理解完整的含义。

改进策略：将硬数据从文本中提取出来，将其放入图表、图形、表格或图片中，附上文字解释。

Lv 5 持续优化体验：检查文章

自查顾名思义就是自己检查文档内容。一般自查文档需要在写完文档后，“冷却”一段时间后再检查内容。这样做的好处是，“冷却”可以帮助你用全新的视角来看待自己的内容，不会陷在“自我欣赏”的怪圈里。自查的要求有哪些？

1. 主题：检查文档的主题是否明确。

• 检查文档的主题是否明确且聚焦，是否符合目标读者的需求。
• 是否在写作的过程中思维过于发散了，导致内容脱离主题，俗称“跑题”。
• 一般文档的内容最好围绕一个主题展开，如果文档的内容存在多个主题，则不够聚焦。

2. 结构：检查文档的逻辑是否清晰。文档内容的“陈列”是否按照一定的逻辑顺序展开？是否符合结构化写作的四个原则：结论先行，以上统下、归类分组、逻辑递进。

3. 标题：检查文档的标题是否精简概括。文档的标题是一篇文档的门面，这个门面是否足够吸引人，又切合实际内容。

4. 内容：检查文档的文字表达是否足够精简。检查文档的文字表达是否做到简单清晰，不“拖泥带水”。

本文原文来自CSDN