如何写技术文章
共 1877字,需浏览 4分钟
·
2020-08-11 21:36
编者按:本文作者文蔺,奇舞团前端开发工程师。
今年在组内推动常态化的分享活动,协助一些同学选题并审阅 ppt 和文章,一直想就其间种种问题做一次总结。虽然自己不怎么动手写博客,但因负责编辑奇舞周刊(weekly.75team.com)1的缘故,这几年接触了大量优秀的文章,耳濡目染,对技术文章的写作也形成了一些自己的看法。
本文将从准备工作、文章结构、注意事项等方面展开,希望对乐于分享的同学有一定启发。
准备工作
动手写文章前,须依次明确两点:目标受众;写作思路。
明确目标受众
谁会看我们的文章?谁会对我们的文章感兴趣?这是撰写文章的首要问题。
动手前,一定要先想好你的目标受众,即文章面向哪些读者。要充分考虑读者的背景。面向的读者不同,语言风格、展现形式等也须有所不同。以技术科普文章为例,你需要提供充足的背景知识,通过场景化、故事性的方式切入主题,并提供一系列简单、可复现的示例。
梳理写作思路
明确受众之后,可以用某种结构化的形式梳理写作思路,如带有层级的列表、思维导图等。如下图所示,正式写作本文前,我使用 markdown 梳理了本文写作的大致思路。
再经几番调整,文章的基本框架便有了,可以开始撰写初稿。当然,这个基本框架也会随着写作的推进不断动态调整。
曲线办法
另外,这里提供一个曲线解决问题的懒人思路。该思路来源于各类技术大会实录。
写文章前,你也可以先做一份 ppt(结构清晰、内容精美者为佳),并将 ppt 转换为图片逐次放入文稿中。
写作时,只当自己在面对观众做现场 presentation,将要说的话适当润色,插入到每张 ppt 前后。注意配以适当的转折语句。
这样的好处有三:图文并茂,适合阅读;信息密度较纯文字高;传达文字不足以完成的信息。
文章结构
优秀文章套路基本相似,问题文章则各有各的缺点。这里我用“起承转合”四字来概括基本套路。
“起”
忘了是谁说的,好的开头是成功的一半。
一般来说,在文章开头,你需要交代写作缘起,如业务遭遇痛点、线上神秘 bug 等。
而后,简要介绍文章将从哪些方面展开、达到什么目的,而读者能从中获得何种收获。
“承”
承接开头,开始按事先整理的大纲,切入正题。可以开始详细介绍相关场景、探索解决方案的历程。
需要注意的是,始终不能忘记目标受众。根据目标受众特点,注意在必要的地方,提供必要的背景知识,如某项技术的发展历史及相关术语介绍。
“转”
经过前面的充分铺垫,话题转入突破阶段。可以详细介绍你所寻找到的突破方案及其效果。如有多种方案,建议同时列出,并加以对比。
“合”
回顾全文,适当总结:
文章解决了什么问题?
还可以进行哪些方向的探索?
有何不足之处?
展望未来
注意事项
在写作过程中,有一些细节需要注意。
切忌以下问题 ——
罗列大量术语:全无背景介绍,直接开始罗列一堆概念
粘贴长篇代码:大篇幅引用代码,影响阅读体验
风格变化无常:时而严肃、学术风,时而卖萌、抖机灵
内容贪图简便:使用代码块、图片或 blockquote 完全取代正文
有以上问题且难以克服者,建议使用前述“曲线办法”,可能一定效果。
总结
以上谈了一些技术文章写作的套路,但更重要的还是日常积累。
当然,日常学习时也要有所甄别,拥抱精品,远离次品。
最新一期的奇舞周刊(第 359 期2)选取的两篇文章质量甚好,附录如下 ——
悟空活动中台 - H5 活动加载优化3 (发表于公众号“vivo互联网技术”)
从 2.9 秒到 0.6 秒,信息流首屏提效 80% 的秘诀4 (发表于公众号“FEPulse”)
另,写完上文之后,有同学给我转发《如何写好一篇技术文章》5,同样建议阅读。
文内链接
https://weekly.75team.com/
https://weekly.75team.com/issue359.html
https://juejin.im/post/6844903504922804238
推荐阅读