本文将分享近段时期以来的技术文章创作心得体会,如果你也正在写作的路上,希望这篇文章能对你有所帮助或启发。

笔者在去年下半年发表了约莫 40 篇文章,几个月内在掘金升级到优秀创作者,达成了里程碑式的小目标,其中一篇文章被官方评选为 2022 年度爆款好文,也算是十分难得的肯定。

为什么写作

技术写作确实没有什么门槛,还会有诸多好处,比如:

加深对知识的理解

写文章需要你对问题展开较为全面的思考,同时这个过程中你也可能会需要查阅资料对观点进行补充,促使你主动持续学习,持之以恒必将大有裨益。

集思广益

文章下开放性的讨论往往可以启发你的想法。

求职亮点

经常写技术文章能在一定程度上证明你的学习力,面试官甚至可以参考你的博客内容对你的水平进行更深层次的评估,这比起口头交谈更有说服力。

提升表达力

能把技术原理讲明白透彻是一种不可多得的能力,文字表达同样也需要长时间的锻炼。

如何开始写作

其实说起来,所有的技术文章大体上都可归为两类:记录分享

对于大部分人来说,很难一开始就创作体系化的文章,所以我起初都是想到什么就写什么,这个阶段比较多都是写些笔记,谈不上真正的文章。

笔者实践类文章写的比较多,以此类型来说的话,一份笔记的生命周期大致如下:

  1. 发现问题(当下遇到的问题可能是解决不了的,可以先记录下)
  2. 解决问题(解决问题的方法,可能是搜索到的,也可能是自己摸索的)
  3. 总结问题(对解决问题过程的经验总结,复盘分析问题产生的原因,思考解决方案是否只存在一个,方案之间的利弊以及是否存在最优解等等)

然而笔记只需要做到自己看得懂就行了,作为具有可读性的文章往往普适度还不够。

当一份笔记进行到上述第三步总结的时候,通常就可以大致形成一篇技术文章的雏形了,接下来就是完善复盘、抽象归纳、内容结构组织、总结等加工。

如何写好文章

当你不再只停留于记录笔记,并开始技术文章的写作和分享时,你一定想知道如何写好一篇文章。

起好标题

标题要能高度概括出文章主旨是什么,最好还能引起读者阅读的兴趣。

有人会说我不想当标题党,其时我觉得所谓标题党应该是指那些仅靠夸张标题博人眼球,实际内容贫瘠甚至牛头不对马嘴的文章。如果你花了许多时间精力创作内容,却对标题敷衍了事,又如何让人相信你的内容真的值得一读呢?

结构清晰

一般我会采取「总-分-总」结构,前言是总结的一部分,包含了文章内容的关键信息提取和介绍,通常是引起读者兴趣,更清楚地表明主题立意,或是说明文章所适合的阅读人群。

整篇文章的内容建议不要太长,太长了容易消磨读者的耐心,太短了只适合写成笔记,很难有阅读价值,所以内容的分段比较考验作者的内容组织的经验和能力。笔者建议文章篇幅大于 500 字不超过 8000 字就可以,观点仅供参考。

保持谦虚

谁都可能有犯错的时候,在技术文章中我们可以适当保持谦虚的态度,希望多听取建议或意见,同时也应避免自己主观的认识给别人带去误导。

写作秘诀之愚见

遍历通读

这不仅是检查错别字,而是把自己代入到读者视角,检查行文是否流畅通顺,笔者没什么天赋,所以每一篇文章在发布前都至少通读了十几遍。

惜字如金

宝剑锋从磨砺出,做减法其实要远比做加法难,要懂得少即是多的道理,文章越精炼越值得一读。

图文并茂

适当配图有利于文章的可读性,同时应该避免大量图片导致排版失衡,图片过大让文章“抖动”影响体验等,例如动图最好剪辑压缩过后再上传。

实践真知

计算机科学的基础还是实践,无论是讲原理还是讲应用的技术文章,都最忌讳空谈。很多人觉得想不出选题,文章不知道写什么,很可能也是缺乏实践的经验,我们毕竟不是为了写作而写作。

写作技巧之愚见

技术文章创作基本都是使用 MarkDown 格式,这种格式语法非常简单,即使完全没有接触过的人,也能在一天之内精通。

同时 MD 格式也是支持大部分 HTML 语法的,比如此处我使用 span 标签呈现一个 12px 字号红色文字;例如我用语义化 HTML 实现如下部分文字隐藏的功能:

查看答案 这是折叠起来的文字内容,你看到我了
1
2
3
4
<details>
<summary> 查看答案 </summary>
这是折叠起来的文字内容,你看到我了
</details>

这里结合个人一些心得体会具体说下排版的小讲究:

  1. 目录嵌套清晰,通常每个段落的一级标题用 ##,接着它的次级标题就是 ### 以此类推。
  2. 看到不少文章用代码块来强调重点词语,虽然在一些主题中确实有高亮效果,但按规范可以用 ** 包裹住加粗来表示强调,也避免了不同网站主题观感不同。
  3. 文章中不要放大段代码,只展示关键代码即可,这样能降低读者的阅读难度,记得三个 ` 后面要加语言描述(如 js、java等),这样才有正确的词法高亮效果,这点经常容易遗漏。
  4. 展示代码除特殊情况下尽量不要用图片。
  5. 代码篇幅大时用在线工具(如码上掘金、codepen等)链接出去,或者把完整代码托管到 Github 仓库当中,尽量别让代码喧宾夺主。
  6. 英文和数字前后一定要加空格,这样更美观易读。
  7. 中文文章写作不要使用半角符(如 , . ; 这些)代替全角符号。

创作工具分享

编写 MarkDown 是可以不需要使用特定软件的,反过来讲则任何编辑器都可以使用,因为最终看到的效果往往也与编辑时不同,所以我们只需要把重心放在内容上。

你甚至可以自己开发一个 Web 编辑器,或是基于 Electron 等技术做个桌面软件,当然使用日常生产工具 VSCode 也是完全没有问题的。

画图工具

  • 流程图工具:

draw.iohttps://app.diagrams.net/

我很少画流程图,不过这个工具我看使用的人比较多,基本有口皆碑。

  • 白板工具

excalidrawhttps://excalidraw.com/

非常好用的在线白板工具,手写风英文也挺有个性,我通常都是画完直接截图粘贴到编辑器中,上手很快。

excalidraw演示

制图工具

在线图片压缩:

https://tinypng.com/ (压缩效果好,支持 API 调用,单文件最大支持 5M)

Gif 在线压缩:

https://compressor.io/

https://www.iloveimg.com/zh-cn/compress-image/compress-gif

在线视频转 Gif:

https://www.apowersoft.cn/video-to-gif-online

这个网站还支持视频变速等功能,适合没有直接录制 Gif 软件时使用录屏工具,然后在这个网站上将录屏转为 Gif 动图。(不过掘金什么时候支持下文章内上传视频鸭)

平台的对比(略)

之前心血来潮尝试在十几个平台发布过技术文章,本来想写一下各社区的体验及感想等,但是我发现很难做横向对比,而且到目前我常更平台也就不超过三个,还包括自己基本没人访问的博客网站,写这些就没什么意义了。

总结

技术写作可以说是一件我尝试过最正确的事情。虽然我并不推荐所有人都参与写作,毕竟确实很花时间,而人的时间精力很有限,应该多多花在你所认为更重要的事情上。

文章开头我谈了为什么而写作,在结尾我更想说说写作对我究竟意味着什么:我觉得是一种成长的具现化。

在一开始的时候,我觉得只要我想写,就会有写之不尽的选题,哪怕是讲个 for 循环(笑),都能长篇大论一番,但没人能够把同样的技术点翻来覆去地写,有时我们也能看到社区上确实存在许多同质化的文章,在意识到这点后,很快就会陷入一种“写无可写”的状态。

而技术写作的特殊之处在于,这种难产的状态并非是”灵感枯竭”,而是触摸到了”边界”的反馈,这意味着你迫切需要进一步的成长。

如果只是一味地“输入”知识,我们总会很容易就感到满足,而“输出”则往往会让你认识自身的局限,只有真正地“吸收”知识,不断扩展边界,才能打破局限。

回过头来看自己写过的文章,就是一种成长的具现化:我时常可以反思自己,一路上是否有在进步;也可以站在当下的角度审视过去,有哪些可以做到更优的地方;甚至也会惊讶于以前做过的某些东西,被自己写的文章唤醒了那些只停留在过去的技术细节。而文章的数据,反而是最不重要的东西。