如何写一篇好的技术文章?

最近一直在写文章,写公众号,但是自己总是隐隐感觉专业性不够。大多数程序员的思维能力跟实战能力尚可,但表达能力一般比较弱(包括我自己)。 今天就特意学习了一下,如何写好一篇好的技术文章。

一 写什么?

关于写什么,其实可以从新颖程度、内容划分两个方面来看。

1.1 从新颖程度划分

关于写什么,在极客时间的《左耳听风》专栏中,皓叔提到要写两类文章:

  • 别人没写过的文章
  • 别人写过,但是你可以写得更好的文章。

第一类 别人没有写过的文章 大多数是比较新的领域,比如区块链等。这种新的领域一般文章比较少,少数仅有的几篇多是来自国外的文章。由于国内网络不太畅通,又有语言屏障,所以国内各大技术博客网站上很少有国人的文章。所以如果你写了,一旦新技术开始流行,这种文章很容易火。但是你得熬过前期受众小这个阶段,坚持写才可以。

第二类别人写过,但是你可以写得更好,这种文章很难。如何能从众多文章中脱颖而出是需要下一番功夫的。一般只有你的博客大多数是高品质的文章,形成好的口碑,有固定的粉丝群,才能被大家搜集到,进而被各大搜索引擎收录且排到前列。此类文章需要你有扎实的技术功底或者好的文笔。

1.2 从内容划分

如果从文章内容划分,其实可以分为如下三类:

  • 解决问题类型
  • 怎么做类型?
  • 介绍知识类型?

其中:
解决问题类型多是你在工作中,或者学习过程中遇到的实际问题以及解决方案。
怎么做类型 一般是某个软件如何安装类型的问题,这种类型的文章多需要详细的操作步骤。
介绍知识类型 是你学习某个知识的总结与反思。

二 怎么准备素材

明确了我们要写什么,接下来就是要准备素材。
素材有很多,那么我们应该怎么选择呢?
一般我自己在准备素材过程中,会遵循一个原则:"是否能够说服我自己?"。 我一般会写一个提纲,把自己的问题列出来,不断地跟自己对话。然后去问题的答案。
一般在准备素材的过程中,有几个需要注意的事项:

2.1 关于知识盲区

有时候我们写作的时候,会遇到一些知识盲区,如果时间紧,或者自己偷懒,会刻意避开,其实这样是不对的。如果我们只是写给自己看,这样可以。但是如果发出来供广大网友来看,我们的知识盲区很大可能也是网友的知识盲区。 如果自己不搞明白,不但自己掌握不深,影响文章质量,也会影响网友对我们的信任度。

2.2 关于掌握的程度

之前在这个问题上,我自己是矛盾的。有时候会想投入很大精力去研究透彻某个知识点,但有时又会考虑整体时间进度、排期等原因,放弃深入研究。今天看文章,发现一个不错的观点:“不用必须自己完全精通,让大多数读者觉得学到了,而且能够应对实际工作需求即可”

三 下笔写作

素材准备好了,那我们进入下一个环节,开始写作。

3.1 原则

写作就是一个与自己对话的过程。在写作过程中,我们需要不断地追问自己

  • 这个知识点确定讲清楚了吗?
  • 这个能否引起读者的共鸣?
  • 这个地方是不是可以更精简?

如果要用某种学习方法来总结写作原则的话,我认为应该是费曼学习法。如何给一个外行人讲明白一个技术问题。 这很难,但是我相信如果我们坚持下去,不但能提升文章的阅读体验,也能提高我们自己学习知识的留存率(就是学完,过了很久能够记住的比例)。

3.2 标题与内容

如上文所述,我们按照内容划分将文章分为三类,那标题跟内容部分,也按照这三类来分别讲一下。

3.2.1 解决问题类型

解决问题类型的标题一般都是XXX的解决方法,XXX的排查过程。其文章结构一般如下:

  • 问题是怎么发现的?
  • 排查问题的详细过程?
  • 总结反思: 是否可以更快发现问题?如果再次避免等。

3.2.2 怎么做类型

怎么做类型的标题一般是如何XXX, 怎么XXX。其文章结构一般如下:

  • 为什么要这样做?
  • 怎么做?
  • 做的过程中遇到了什么问题?

此类文章,需要分步说明,而且要写详细。最好也标明是什么环境、写明预期结果。

3.2.3 介绍知识类型

介绍知识类型,也就是某项知识的介绍。一般标题是什么是XXX, XXX简明介绍。其文章结构一般是:

  • 什么是?
  • 为什么是?
  • 它的优缺点?
  • 它的原理?
  • 同类型的对比
  • 总结

四 打磨

之前我写文章,一般写完就急匆匆发出去,其实现在想想是不对的,需要反复打磨一下。换位思考一下:“如果读其他人的文章,到处是错别字,体验肯定会很差”。
哪些地方需要我们打磨一下呢?

  • 首先是错别字,错句,重复啰嗦的地方
  • 其次是调整上下文衔接比较牵强的地方
  • 再次是通过加粗、划线、标红等方式,将某几个(不要太多)重点的地方标注一下。
  • 最后就是排版问题。比如像编号、代码、章节层级缩进等。

五 规范与注意事项

写文章其实还有好多的注意事项,我们平时做事情也遵循类似的原则。比如

  • 重要的事情说三遍:也就是重点多重复。
  • 重点放前面,普适的方法放前面:毕竟人的精力有限,可能没有耐心看到最后。
  • 一图胜千言:复杂流程适当用图片展示,便于理解
  • 知错能改:我们都不是圣人,肯定有知识盲区,不要害怕观点错误,也不要因为观点不确定就不敢写,要勇敢。我们不表达,别人怎么给我们指出,我们怎么进步呢?

如果你对文字排版、格式、数字等中文文档规范细节有追求,可以参考阮一峰老师的文章 https://github.com/ruanyf/document-style-guide

六 总结

本文结合自己近期的痛点,从写什么、怎么准备素材、写作、打磨以及规范这五个环节讲解了如何写一篇好的技术文章。希望这篇文章对有类似需求的人有帮助,感谢~

七 参考文献

《中文技术文档的写作规范》 https://github.com/ruanyf/document-style-guide
《如何写好一篇技术文章》 http://1t.click/aPk2
《写好一篇博客,只需四步》 https://blog.csdn.net/my_truelove/article/details/72895870

八 其他

如果有疑问,可以直接留言,也可以关注公众号 “链人成长chainerup” 提问留言,或者加入知识星球“链人成长”,期待与您共同成长~

推荐阅读更多精彩内容