一、前言

作为一名程序员,会经常在网络上查找各种各样的资料。此时,会检索到很多优秀的技术文章。一篇好的技术文章,可能不仅仅会解决我们的问题,更能在阅读的过程中带给我们一些美好的体验。

许多时候我们也憧憬自己能写出优秀的技术文章,然而却往往感觉到无从下手。那如何写好一篇技术文章呢?其实是存在一些方法和技巧的,下面我们就对这些内容进行详细的介绍。

二、写作目的

在正式介绍如何写技术文章之前,我们先来看下为什么要写技术文章?因为知道了我们的目的,才能有动力更好的完成写作。

2.1 写给自己

可能看到这个标题之后,大家的第一反应是感到疑惑。因为在大多数人心目中,写技术文章的主要目的不是给他人分享自己的知识么?

针对这个疑惑,我的回答是:

  1. 对于技术文章的读者而言,能够学到一些知识或者解决自己遇到的问题,确实很有意义。不过,大部分技术文章主要是针对某些特定的知识点进行阐述。因此,对于读者的益处主要是查漏补缺,想要通过阅读技术文章形成自己的知识体系就比较困难了。
  2. 对于技术文章的作者而言,通过写作能够获得更大的益处。其实,与其说是写作,倒不如说是 “学习+思考+总结+提升” 这一整体的过程。写作本身就是一个学习的过程,而不仅仅是写出一篇文章。

所以,对于大多数希望学习和成长的同学而言(例如我自己),写作的主要目的是自身的提升。

2.2 总结学习成果

我们在日常工作中,会遇到许多问题,也会想到各种各样的解决办法。随着解决的问题越来越多,我们了解的知识点也越来越多。但是,这些知识点我们应当如何沉淀下来形成知识体系,便于后续解决类似的问题呢?

写作,恰好可以作为对前一阶段学习成果的总结,将这些零散的知识点串联成自己的知识网络。对于这一过程,可以使用一幅图来表示,如图 2-1 所示:

图 2-1 知识点串联成知识网络

2.3 明确学习方向

为了说明通过写作如何明确自己的学习方向,首先列举下在简书上我的文章分类,如图 2-2 所示:

图 2-2 简书上的文章分类

对于我而言,通过已写的文章就可以明确大致的学习方向,原因如下:

  1. 可以了解自己知识体系中擅长哪些知识。例如,通过图 2-2 所示可以知道,我曾经写过 iOS 多线程系列的技术博客。因此,对于 iOS 多线程的相关知识我应当比较擅长。
  2. 了解自己擅长哪些知识之后,自然也就知道了自己知识体系中欠缺哪些知识。因此,对于这部分知识可以重点关注。
  3. 便于回顾已经掌握的知识。由于已写的文章都可以归纳到对应的知识点中,如果需要回顾某些知识点,就可以迅速找到相关的文章进行查看。

在了解自己知识体系的前提下,学习的方向性就会强上许多,这也是写文章的益处所在。

2.4 良好的学习方式

“谢谢楼主!您这篇文章给我的收获很大”;

阅读量 10000+;

”您的文章已被《xx进阶之路》专题收录“ 等等。

每当看到这些信息的时候,都会感觉很开心,因为自己获得了别人的认可。此时,对于学习和写作都会产生更大的兴趣。一旦兴趣有了,学习效率更容易提上去。这里分享一个从知乎上看到的学习金字塔模型,如图 2-3 所示:

图 2-3 学习金字塔模型

从图 2-3 可以知道为什么写作是一种提高效率的学习方式,因为写作正是一种 ”教授给他人“ 的主动学习方式的最好体现!

2.5 思考体系化

书面表达与口头表达最大的差异是:口头表达只需要告诉对方发生了什么,而书面表达需要把一个事情全面而透彻的讲清楚。如果想要讲清楚一个事情,就需要建立一个清晰的思考体系。

写作创造了一个能够升级思考的契机,让你可以把点连成线汇成面。例如,当你需要给刚做过的项目写一份总结文档,为了便于读者的理解,你需要考虑以下几点:

  • 我做这个项目是为了解决什么问题?
  • 业界其他团队在面对这个问题时会采用什么方案?
  • 我的方案与他们的方案对比起来有什么优势?
  • 未来有哪些潜在的可迭代优化的方向?

而当你把这些问题都想明白写清楚,就形成了一个清晰的思考体系,自然会取得更大的进步。

在上述的几节中,我们使用大量的篇幅阐述了写作的目的。原因就是希望大家能够理解:写作,首先是一条自我成长之路。

三、写作步骤

明确了写作目的之后,接下来就该详细介绍如何写一篇技术文章了。

在写文章之前,先想清楚以下几个问题:

  • 是写给谁看的?
  • 主题是什么?
  • 提纲怎么写?

如果这几个问题想清楚了,文章自然也就水到渠成了。

3.1 目标用户

首先分析文章会给谁看,即文章的目标用户。有了目标用户之后,才知道需要产出一篇什么样的文章。例如,你的目标用户是从未接触过 iOS 的群体,他们可能连 Xcode 都没有安装过。如果上来就讲 iOS App 性能调优,这基本会导致你的目标用户感觉不知所云。但是,如果你的文章面向的是更深层次的探讨和分析,为了这部分未接触过 iOS 的用户去增加篇幅大可不必,只会让那些中高级程序员觉得这篇文章废话连篇,原本的价值大打折扣。

实际上,一篇文章不可能面面俱到。即使是书籍,也会有一个读者群体。因此,首先应当明确文章的目标用户。

3.2 确定主题

文章主题涵盖的范围不宜过大,写大而全的东西对作者的水平要求非常高且需要消耗大量精力。如果真想写,也应当先把思路理清,与有经验的人交流之后再开始。

挑选的主题应当是自己了解透彻的东西。如果对于一些细节不太了解,也务必将这些细节点叙述清楚。

3.3 寻找知识点

主题确定好之后,围绕这个主题会有许多相关的知识点,可以通过网络或者其他的方式找到一些阐述主题所需的知识点。

例如,我们想写一篇主题为 iOS crash 分析的文章。围绕这个主题寻找资料,可以找到诸如 crash 的类型、出现的原因、如何收集、如何避免、出现 crash 不让程序崩溃的方法等相关知识。

然后,挑选我们需要介绍的知识点。如果这篇文章主要是讲解如何收集 crash,那就可以将 crash 类型、出现的原因、如何收集这些知识点列入阐述主题所需的知识点,而如何避免等相关知识就不需要列入我们所介绍的范围。

3.4 提纲和标题

确定主题和所需知识点之后,将需要介绍的知识点按照逻辑顺序或者内容由浅入深进行排列,形成一个提纲。

定义提纲是有技巧的,对于技术文章,基本都是有结构可循的,提纲标题尽量做到言简意赅。

例如,在上一步中我们已经确定好所介绍的知识点为 crash 类型、出现的原因、如何收集,结合技术文章的基本结构,提纲按照由浅入深就可以列为:

1. 前言(基本结构)

2. crash 收集(一共两种 crash,分别介绍类型、出现的原因、如何捕获)

2-1. NSException

  • NSException 类型常见的异常
  • 常见异常出现的原因
  • 如何捕获

2-2. Unix 信号

  • Unix 信号类型常见的异常
  • 常见异常出现的原因
  • 如何捕获

3. 踩过的坑(可以根据实际情况确定是否需要)

4. 总结(基本结构)

5. 参考文献(基本结构)

6. 联系方式(可以根据实际情况确定是否需要)

根据主题和提纲,设计一个突出中心的标题即可。例如,根据上面例子中的主题和提纲,文章的标题可以设计为《漫谈 iOS crash 收集》、《iOS crash 收集原理》等。

3.5 完善内容

提纲一旦确定,剩下的工作就是将内容填充到各个目录之中。

这里需要注意的是,完善内容时尽量做到下面几点:

  • 内容正确
  • 图文并茂
  • 语句通顺
  • 格式合理
  • 举例说明

3.6 反复修改

一篇优秀的技术文章并不是写出来的,而是改出来的。文章初稿形成之后,可以把自己想象成读者,尽量多读几遍,反复修改之后达到通顺易读即可。

四、写作技巧

4.1 开始

万事开头难,写作也是一样。不论现在是什么样的水平,如果想提高写作能力,最好的方式就是开始写。可能开始写的几篇文章不够好,但是随着数量的增加,一定会导致质变的产生。

4.2 模仿

写出第一篇优秀的文章将会是一个良好的开端。但是,对于那些写作新手来说,这往往也是最困难的,很多人会觉得无从下手。针对这种情况,我的建议是从模仿开始。有些读者可能目前还不善于写作,但一定阅读过那些优秀的文章,不妨模仿那些优秀的文章,学习他们是如何给文章起标题的、如何写开场白、如何阐述他们的观点以及如何总结的。通过模仿,会渐渐培养起写作的感觉,并且越写越好。

4.3 多写

任何事情都不能一蹴而就,写作也是。想要写出优秀的文章,最好的方式还是反复练习。熟能生巧,写的多了自然会更容易写出优秀的文章。

4.4 内容技巧

在写具体内容时也有一些技巧,例如:

  • 使用合适的称呼。为了让读者感受到阅读这篇文章就像是在和作者对话一样,文章中可以用 “我” 或 “我们” 来表示作者,用 “您” 或 “大家” 表示读者。
  • 对长句进行断句。要多用短句,避免长句,目的是让读者阅读起来体验更好。
  • 采用多种表达方式。正所谓 “一图胜千言”,对于文字不好表达的地方可以考虑使用插图、表格等形式。
  • 文末总结。文章结尾时一定要有总结,让读者读完文章后,能够快速抓到重点,有一种 “深入浅出” 的体验。

五、总结

本文基于自己对于技术文章写作的一些感悟,同时结合了一些指导写作的优秀文章,总结了写作步骤和写作技巧,希望能给大家在技术文章写作的过程中提供一些帮助。由于时间仓促,个人水平有限,如有错误之处欢迎大家批评指正。

最后,引用之前看到的一句话作为本文的结束:”写作本身是一件非常有意义的事情,它将使你变得更加勤于思考,思维也将变得更加成熟与完善。同时,你也会为自己用心写出的每一篇文章而感到骄傲,并从中获得信心“。

六、参考文献

【编程之外】为什么我们要写技术文章?

知乎上极力推崇读书的人为什么不把上知乎的时间都用来读书?

写文章对程序员很重要吗?

你也可以写出优秀的技术文章

如何写好一篇技术文章?

技术写作是有技巧的

七、本文作者

神策数据 | iOS 研发工程师

我是温泉(这里不是笔误,我的名字就叫温泉),热爱开源,热爱技术,目前专注 iOS 领域,期待每天都能进步一点点。
爱好阅读历史相关的书籍,闲暇时会约上三五好友一起出去走走。

八、交流合作

本文著作权归神策数据开源社区所有。商业转载请联系我们获得授权;非商业转载请注明出处,并附上神策数据开源社区公众号二维码。
你还可以扫描二维码,加入社区交流群,与大家一同讨论。
也欢迎关注我们的公众号,博客更新尽在掌握。