如何写好一篇技术文章

Posted 2022-11-10 Jerish_C

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

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

选题

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

• • 技术笔记积累

  • 想到的一些技术思路

  • 开源项目介绍与实现思路

技术笔记积累

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

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

技术思路积累

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

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

开源项目介绍与实现

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

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

1. 1. 适用场景

   2. 使用流程

   3. 参数介绍

   4. 更新日志

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

预研与实现

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

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

1. 技术上是否可行？

2. 是否能解决一些项目的实际痛点？

3. 是否已有类似的文章或方案？如果有，新方案的优势是什么？

4. 接入成本？完全Plugin还是需要变动引擎？

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

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

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

   2. 对工程向的内容，要提供测试案例所有代码

   3. 要经过自己的调试验证

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

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

文章结构

技术文章的结构，我一般遵循五段式：

• 当前的需求和痛点、现有方案的不足

• 新的技术方案的思路

• 实现上的问题、对应技术分析

• 成果展示

• 总结、参考资料汇总

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

迭代

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

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

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

1. 1. 实现、思路上的优化

   2. 新技术的适配

   3. 原内容的扩展

   4. 同类技术知识的补充

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

• • UE 资源合规检查工具 ResScannerUE[1]

    https://imzlp.com/posts/11750/
    

  • 虚幻引擎中的属性面板定制化[2]

    https://imzlp.com/posts/26919

  • 基于 ResScannerUE 的资源检查自动化实践[3]

    https://imzlp.com/posts/20376/

  • UE 中多阶段的自动化资源检查方案[4]

    https://imzlp.com/posts/22655/

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

发布

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

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

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

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

工具

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

• • 博客生成：Hexo

  • 部署：Github Actions

  • MD编辑器：Typora

  • 图床：PicGo/腾讯云OSS

  • 笔记记录：Lepton

  • 画图：draw.io

  • 截图：Snipaste

  • 同步：Dropbox

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

结语

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

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