循迹研究:如何写好一篇技术文章

How to write a good technical article

技术文章是能够有效锻炼表达能力和进行技术积累的方法。与单纯的技术笔记不同,我认为的技术文章应该是对实际的问题新技术思路的解决方案,而不是技术点的简单堆砌。

对于如何写一篇我认为合格的技术文章, 最近做了一些思考,本篇文章会探讨我写文章时的一些思路和步骤,以及工具推荐和CI/CD自动化发布的实现。

选题

我对于技术文章的选题,其实没有一个明确地目标来决定下一篇写什么内容。主要是利用平时积累的技术笔记中发现一些新的技术或优化思路,深入研究拓展为一篇文章。主要idea来源为以下三方面:

  • 技术笔记积累
  • 想到的一些技术思路
  • 开源项目介绍与实现思路

技术笔记积累

技术笔记虽然通常都是单个的技术点,但在积累的过程中,会发现多种技术点的组合,就能实现一些很有用的点子。也能够根据新积累的技术点与现有的实现进行组合,让已有的技术方案更加方便和易用。

日常的技术积累非常重要,不单单是为了写文章,而是要对接触到的内容做一个整理和复盘。整理的过程中会加深理解,而且记录下来也方便需要时查找。技术是用进废退的,某个内容长时间不再接触,很容易忘记,但如果及时地记录下来,可以在需要时快速地上手,避免重复研究的成本。

技术思路积累

除了从技术笔记中积累外,还会记录脑海中偶尔蹦出来的一些其他的技术或者优化思路,作为备用选题。只包含一两句话的简单描述,如:

我会不定期地从这些选题中,进行深入地研究和工程上地实现,将其总结为一篇技术文章。

开源项目介绍与实现

博客中的有一部分文章,是介绍我的开源项目和实现的。开源项目也是一个技术产品,技术文章就是产品文档。

这种把项目和文章作为产品的方式,可以培养从产品使用者角度考虑的思维。内容应该涵盖以下几点:

  1. 适用场景
  2. 使用流程
  3. 参数介绍
  4. 更新日志

对开源项目文档的维护是个不小的工作量,技术上的实现会发生变化,但经常无法及时地更新文档的内容,这也是个人精力的局限性,应该发挥社区的力量来共建。

预研与实现

在确定技术文章选题之后,会确立一个实现上的具体目标,验证可行性,对整个技术思路的进行验证。通常这个步骤不会有什么问题,因为日常积累的技术点是现成的,只需要以一种合适地形式使用。

以UE的技术文章为例,对于文章的选题,预研时首先要确定以下几个问题:

  • 技术上是否可行?
  • 是否能解决一些项目的实际痛点?
  • 是否已有类似的文章或方案?如果有,新方案的优势是什么?
  • 接入成本?完全Plugin还是需要变动引擎?

技术应该具有通用性,尽量降低接入成本的方式实现方案。有些实现需要修改引擎,应该尽量避免,可以采用一些Hack技巧的替代实现。因为对引擎的变动是一个较为重度的行为,无法支持Epic Launcher中的预编译引擎,接入成本较高,并且针对不同的引擎可能要分开适配,无法做到技术的通用性。在实现的过程中,尽量避免对引擎的变动,以及考虑跨引擎版本的实现。

对于文章描述的技术细节,内容上有以下几点要求:

  1. 要对关键代码的调用栈截图

  2. 对工程向的内容,要提供测试案例

  3. 所有代码要经过自己的调试验证

  4. 对引用的技术描述要记录出处

技术文章毕竟是公开的内容,对于相同需求的开发者可能会起到指引作用,如果作者都模棱两可,很有可能会误人子弟。所以写技术文章要力求表达的准确性。

文章结构

技术文章的结构,我一般遵循五段式:

  • 当前的需求和痛点、现有方案的不足
  • 新的技术方案的思路
  • 实现上的问题、对应技术分析
  • 成果展示
  • 总结、参考资料汇总

把写这篇文章的前因后果,实现方式,依赖的技术点,以及最终成果的数据、性能对比、后续的优化思路、参考资料等等表达清楚。

迭代

技术文章的内容,局限于当时的技术水平和当时技术环境。如果后续有更好的实现方式、或者后续引擎版本的更新,之前的内容不再适用,就需要对过往的文章进行修订。

这也是对过往技术内容重新整理的过程,文字内容可以很方便地实现迭代,视频内容就无法做到这一点。之前我也录制过几个技术视频,但是内容都随着技术和引擎版本的更新而过时,无法修改。这也是我不喜欢录视频的原因之一。

对技术文章的内容迭代,可以概括为以下几个方面:

  1. 实现、思路上的优化
  2. 新技术的适配
  3. 原内容的扩展
  4. 同类技术知识的补充

以博客内关于资源检查的方案系列文章为例:

按照发表时间顺序排列,文章的发表趋势是“先有一个实现方案”,根据日常的技术积累不断地优化和提升已有的实现。在此过程中,又会发现一些新的技术内容,形成正向的技术输出和输入循环,进一步地积累技术笔记,循环往复。

发布

我基于Hexo的博客系统构建的一整套完整的CI/CD发布系统。从创建、编辑、发布、更新,可以一键式地实现。

CI/CD是持续集成和持续部署的工作流,应用在博客内容的发布流程上非常合适,基于Github Action的push hook实现的。把技术性思维应用在生活中,可以极大地提升效率。

本地只需管理所有的原始markdown文件,完整的发布流程都是自动化的。甚至我基于iOS的快捷指令还写了一个快速发布的选项,可以在内容编辑之后,点一下自动发布新的博客内容。

甚至喊hey siri,更新博客,也能实现更新,中二气息拉满。

工具

工欲善其事,必先利其器。虽然写文章最重要的是内容,但是趁手的工具,可以让创作的过程如虎添翼。这里推荐一些我日常使用的工具。

  • 博客生成:Hexo
  • 部署:Github Actions
  • MD编辑器:Typora
  • 知识管理:Obsidian
  • 图床:PicGo/腾讯云OSS
  • 笔记记录:Lepton
  • 画图:draw.io
  • 截图:Snipaste
  • 同步:Dropbox

工具只是辅助,还是坚持输出内容,不要做工具的奴隶,把时间都浪费在折腾环境上。

结语

本篇文章记录了我日常写技术文章的思考和创作流程,把CI/CD技术应用在文章发布中的实现,以及日常使用的工具推荐。

写文章是一个让我觉得快乐的事情,能进行技术积累、输出价值。就像本站的描述那样,每一篇文章都是一个成长的过程。

全文完,若有不足之处请评论指正。

微信扫描二维码,关注我的公众号。

本文标题:循迹研究:如何写好一篇技术文章
文章作者:查利鹏
发布时间:2022/09/12 20:18
本文字数:2.4k 字
原始链接:https://imzlp.com/posts/23932/
许可协议: CC BY-NC-SA 4.0
文章禁止全文转载,摘要转发请保留原文链接及作者信息,谢谢!
您的捐赠将鼓励我继续创作!