如何写好一篇技术文章?

本文主要针对想在掘金等技术社区公开发表文章的同学,面向个人写作的笔记等内容不在本文讨论范围内。同时,我认为面向个人写作的任何东西都不宜在社区公开。

选择合理的内容
技术那么多,到底哪种适合写哪种不适合写?

常见的适合成文的内容有:

  • 新出现的技术
  • 工程中解决问题的方法
  • 高深问题的剖析
  • 被大多数人忽略的重要细节

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

一个小技巧是:在写文章之前,先把自己想写的主题用搜索引擎中搜一下,考虑自己是否有信心有能力超过已有文章。如果没有相关文章,那么可以先写入门级的内容,根据社区反馈逐步深入。

确保内容的准确性

自己挑选的写作内容多是自己摸透了的东西,但是在细节上可能有模糊不清的地方。注意,你模糊不清的地方也正是许多人看此文的动机,务必查阅文献将此处叙述清楚!但又不可沉溺于细节之中,以能讲明白上下文为宜(更深入的细节适合另起一文)。另外,类似选型、对比、趋势一类的文章,对行业整体的把握也非常重要,在表达自己的观点之前,应该充分了解其它人的看法,尤其是和自己观点相左的看法。

写作手法

技术文章的一大特点是文章逻辑严密,层级分明。因此在写作之前,应先列好提纲,根据内容层级由浅入深。

大部分技术知识可以用代码讲清楚,那么此处务必贴出代码。代码应该结构清晰,逻辑简单,能讲清楚问题就好了。一些关键代码需要有清晰的注释。如果有 demo,可以放上 demo 的链接。

文章第一段应该交代清楚文章的受众以及所需的前序知识。最好能用 2~3 句话对文章所要表述的内容进行概括。

文章的遣词造句也很重要,在深入叙述细节之前,宜先主动抛出一个问题。比如接下来要讲矩阵相关知识,就可以提问:什么是矩阵呢?然后再对矩阵做出介绍。这样可以引导读者思考,跟上作者的写作思维。

在对高深内容或者细节进行描述时,即使前文已对相关名词做出了解释,也不应该堆砌专有名词。尽量用白话或者类比的形式将问题解释清楚,文字叙述不清楚的地方,请作图。

版面

相信大部分技术人都有轻度洁癖,所以版面的整齐和缩进无需多言。提几点会让版面看起来清爽的建议:

  • 将“ ”替换为「 」
  • 英文与中文之间空一格。比如 juejin.im 这样的形式。
  • 段与段之间空一行
  • 代码块务必渲染。

标题

UC 式的标题的确可以吸引人,但是技术文章的受众是长期活跃在互联网上的人,对震惊体早已有抵抗力。不如务实一些,让读者能根据标题就对文章要讲什么有大概的了解。短期看损失了阅读量,但从长远来看,是树立个人品牌的好办法。

总结

总的来说,一篇优秀的技术文需要有

  • 简洁朴实的标题
  • 不易重复的内容
  • 内容表述准确
  • 细节描述清析
  • 良好的格式和排版

成文之后,须通读一遍文章。将自己代入读者的思维,边读边考虑在没有为写作本文而学习的知识的前提下,能否读懂文章。

写文章是个非常消耗脑力、体力和时间的事情,在动笔之前,Think Twice ~

另外,在掘金写文章可以换百元好书

感谢:@守候你 @zw.will @sunshine小小倩 @zimo @axuebin @天方夜 @染陌 对本文的建议。

关注下面的标签,发现更多相似文章
评论
说说你的看法