如何写技术文章

我会带着你远行 2022-11-26 07:43 221阅读 0赞

编者按：本文作者文蔺，奇舞团前端开发工程师。

今年在组内推动常态化的分享活动，协助一些同学选题并审阅 ppt 和文章，一直想就其间种种问题做一次总结。虽然自己不怎么动手写博客，但因负责编辑奇舞周刊（weekly.75team.com）1的缘故，这几年接触了大量优秀的文章，耳濡目染，对技术文章的写作也形成了一些自己的看法。

本文将从准备工作、文章结构、注意事项等方面展开，希望对乐于分享的同学有一定启发。

## 准备工作 ##

动手写文章前，须依次明确两点：目标受众；写作思路。

### 明确目标受众 ###

谁会看我们的文章？谁会对我们的文章感兴趣？这是撰写文章的首要问题。

动手前，一定要先想好你的目标受众，即文章面向哪些读者。要充分考虑读者的背景。面向的读者不同，语言风格、展现形式等也须有所不同。以技术科普文章为例，你需要提供充足的背景知识，通过场景化、故事性的方式切入主题，并提供一系列简单、可复现的示例。

### 梳理写作思路 ###

明确受众之后，可以用某种结构化的形式梳理写作思路，如带有层级的列表、思维导图等。如下图所示，正式写作本文前，我使用 markdown 梳理了本文写作的大致思路。

![format_png][]

再经几番调整，文章的基本框架便有了，可以开始撰写初稿。当然，这个基本框架也会随着写作的推进不断动态调整。

### 曲线办法 ###

另外，这里提供一个曲线解决问题的懒人思路。该思路来源于各类技术大会实录。

写文章前，你也可以先做一份 ppt（结构清晰、内容精美者为佳），并将 ppt 转换为图片逐次放入文稿中。

写作时，只当自己在面对观众做现场 presentation，将要说的话适当润色，插入到每张 ppt 前后。注意配以适当的转折语句。

这样的好处有三：图文并茂，适合阅读；信息密度较纯文字高；传达文字不足以完成的信息。

## 文章结构 ##

优秀文章套路基本相似，问题文章则各有各的缺点。这里我用“起承转合”四字来概括基本套路。

### “起” ###

忘了是谁说的，好的开头是成功的一半。

一般来说，在文章开头，你需要交代写作缘起，如业务遭遇痛点、线上神秘 bug 等。

而后，简要介绍文章将从哪些方面展开、达到什么目的，而读者能从中获得何种收获。

### “承” ###

承接开头，开始按事先整理的大纲，切入正题。可以开始详细介绍相关场景、探索解决方案的历程。

需要注意的是，始终不能忘记目标受众。根据目标受众特点，注意在必要的地方，提供必要的背景知识，如某项技术的发展历史及相关术语介绍。

### “转” ###

经过前面的充分铺垫，话题转入突破阶段。可以详细介绍你所寻找到的突破方案及其效果。如有多种方案，建议同时列出，并加以对比。

### “合” ###

回顾全文，适当总结：

*  文章解决了什么问题？
 *  还可以进行哪些方向的探索？
 *  有何不足之处？
 *  展望未来

## 注意事项 ##

在写作过程中，有一些细节需要注意。

切忌以下问题 ——

*  罗列大量术语：全无背景介绍，直接开始罗列一堆概念
 *  粘贴长篇代码：大篇幅引用代码，影响阅读体验
 *  风格变化无常：时而严肃、学术风，时而卖萌、抖机灵
 *  内容贪图简便：使用代码块、图片或 blockquote **完全取代正文**

有以上问题且难以克服者，建议使用前述“曲线办法”，可能一定效果。

## 总结 ##

以上谈了一些技术文章写作的套路，但更重要的还是日常积累。

当然，日常学习时也要有所甄别，拥抱精品，远离次品。

最新一期的奇舞周刊（第 359 期2）选取的两篇文章质量甚好，附录如下 ——

*  悟空活动中台 - H5 活动加载优化3 （发表于公众号“vivo互联网技术”）
 *  从 2.9 秒到 0.6 秒，信息流首屏提效 80% 的秘诀4 （发表于公众号“FEPulse”）

另，写完上文之后，有同学给我转发《如何写好一篇技术文章》5，同样建议阅读。

## 文内链接 ##

1.  https://weekly.75team.com/
2.  https://weekly.75team.com/issue359.html
3.  [https://mp.weixin.qq.com/s/6gtVR0nVNcZvREjwftZgzA][https_mp.weixin.qq.com_s_6gtVR0nVNcZvREjwftZgzA]
4.  [https://mp.weixin.qq.com/s/dGO7cvhnr0cWdeu7O2v5Eg][https_mp.weixin.qq.com_s_dGO7cvhnr0cWdeu7O2v5Eg]
5.  https://juejin.im/post/6844903504922804238

## 关于奇舞周刊 ##

《奇舞周刊》是360公司专业前端团队「奇舞团」运营的前端技术社区。关注公众号后，直接发送链接到后台即可给我们投稿。

![format_png 1][]

[format_png]: /images/20221124/fecd5e739ba34f748314a60819b2e845.png
[https_mp.weixin.qq.com_s_6gtVR0nVNcZvREjwftZgzA]: https://mp.weixin.qq.com/s?__biz=MzI4NjY4MTU5Nw%3D%3D&idx=1&mid=2247487474&scene=21&sn=b7e0899fef13871cbfc050e898fc876a#wechat_redirect
[https_mp.weixin.qq.com_s_dGO7cvhnr0cWdeu7O2v5Eg]: https://mp.weixin.qq.com/s?__biz=MzI4NzEyMjUxMA%3D%3D&idx=1&mid=2649069242&scene=21&sn=32384deefd70300b9599f9e945e12b38#wechat_redirect
[format_png 1]: /images/20221124/cb7b5a5239684bf98f4281f6da4b7ca2.png