如何入门技术写作 - 来自8年技术博主的分享

我们知道，技术写作能力是求职升职的加分项。求职时，优秀的技术博客有利于拿到 Offer。工作时，编写可读性好的技术文档，同事会感谢你。晋级时，条理清晰，有说服力的PPT，有利于晋级成功。

但是，很多程序员擅长写代码，但不擅长写技术文章。我写技术文章有 8 年了，总共写了 300 多篇文章。“倚老卖老”，我来分享一些技术写作技巧吧~

技术写作路上的拦路虎

技术写作一般会遇到 5 个问题：

1. 不敢写。担心写的不好，被人笑话。

2. 素材从哪来？想写，但不知道写些什么。

3. 内容如何组织？主题想好了，内容有很多，哪些该写，哪些不改写。内容之间的关系是怎样的。

4. 如何把内容表达清楚？如何让内容有说服力？

5. 如何坚持写作？

对于问题1，没人天生都能写出好文章，都需要一个成长的过程。不要太在意别人的看法。

对于问题2，3，4，对应的是写作过程中的问题。写作的过程可以分为 3 个步骤：选主题，列大纲，写内容。本文在后面会着重聊这块。

对于问题5，把写作培养成习惯后，坚持就容易了。按 SMART 原则^[1]，来给自己的写作定计划。每次达成目标，给自己奖励。把写作计划告诉什么的好友，也利于目标的达成(我们都是爱面子的人-_-)。给自己一些成功暗示，如果能成为了大V后，会。。。

选主题

选主题包含 3 块内容：找素材，定主题，起标题。

找素材

素材从哪来？

素材从日常中来。按来源可以分为：

• 经验分享。如：工作中遇到的技术问题，把解决的过程记录下来。

• 学习笔记。如：框架，第三方库，工具的学习笔记。

• 复盘反思。如：做完项目的复盘，月度，年度复盘。

• 主动找。如: 从当前技术趋势的中找: 指数(GitHub 趋势^[2]，百度指数^[3]，Google 指数等)，行业会议，技术文章，热门问答等。

按主题类型可以分为：

• 技术类。包括：代码质量，开发效率，性能优化，安全，用户体验等。

• 管理类。包括：团队文化建设，制度的设计，团队目标的沟通，人员的育，选，留等。

• 软技能。包括：协作能力，解决问题的能力，学习能力等。

定主题

有了素材后，要把素材做一定的抽象，提炼成一个主题。比如：前端异常的处理方法汇总，省空间的包管理神器 - pnpm。

太大的主题，不适合阅读。对于大主题，可以将其拆分成多个小主题，或者缩小主题的范围。比如：主题是 《前端性能优化》。可以拆分成至少 5 个主题：《前端加载性能优化》，《CSS 性能优化》，《JavaScript 性能优化》，《Vue 性能优化》，《React 性能优化》。缩小主题的范围：《前端性能优化最重要的 3 个技巧》。

起标题

标题是主题的直观体现。标题明了直观就好。如：《JavaScript 简明教程》，《导致内存泄漏的原因分析》。

如果要起个吸睛的标题，有一些套路。具体自行百度，我这里就不展开了。

列大纲

大纲是文章的结构。技术文章，一般包含这些要素：背景/提出问题，是什么，为什么，怎么做，结果是怎样，总结。大纲就是列出这些要素，控制这些要素的先后顺序。我们来看 《省空间的包管理神器 - pnpm》 的大纲：

• pnpm 出现的背景介绍。=> 背景。

• pnpm 介绍。=> pnpm 是什么。

• pnpm 的优势。=> 为什么用 pnpm。

• pnpm 的使用方法。=> 怎么用 pnpm。

• pnpm 实际使用的体验。=> 结果怎么样。

组织内容的常见结构

结构是内容之间的关系。不同的内容，适合用不同的结构。

时序结构

时序结构就是按照时间顺序来描述。当介绍的内容和时间有关系时，考虑用时序结构。如：介绍技术的演进过程。

总分总结构

总分总结构就是先介绍整体(总论点)，再介绍局部(分论点)，最后再做个总结。介绍局部时，可以采用 MECE 法则：相互独立，完全穷尽(Mutually Exclusive Collectively Exhaustive)。用总分总结构让内容显得清晰，有条理。因此，总分总结构是在文章中最常见的结构。

推荐阅读：《金字塔原理》^[4]。

分论点的结构

分论点的结构，有并列结构，对比结构和递进结构。

写内容

列完大纲，就开始写内容了。写内容有如下的技巧。

结论先行

结论先行就是先写结论，然后再说理由。

有个同事到你电脑旁边，然后说：“进入A页面，点这个按钮，然后怎么没反应了？”你可能会一脸蒙，这是要干嘛？只是告诉我下，还是我的代码出 bug 了？还是需要我协助？

如果用结论先行的说法: “我这个有个技术问题搞不定。你有空帮我看下吗？过程是:...， 我期望:...，但实际情况是..."。

结论先行，让读者心里有个预设，知道下面会说什么。

逻辑正确

技术文章的逻辑正确性特别重要。常见的有问题的逻辑：

• 以偏概全。比如：我身边的程序员都很少加班，因此程序员很少加班。

• 偷换概念。比如：钱可以买到爱情，因为约会啊、生孩子啊都要钱。

必要概念的解释

有些概念，你知道，但别人不一定知道。因此，要对一些概念做解释。如果觉得某概念不是一两句话说的清的，可以做个简要的介绍，并附上详细解释的链接。

用数据和例子来表明观点

用数据能提升观点的说服力。用例子能帮助读者理解你的观点。

合理的使用图片

有些时候，一图胜千言。比如：用流程图来描述算法，用饼图来展示各个成分的占比情况。

在文章中穿插些 GIF，可以让内容显得轻松。

保证语句通顺

写完后要多读几遍，保证语句的通顺。顺带把错别字修了。

特别长的句子，不容易理解。可以拆成若干个短句。

书写规范

有研究显示，打字的时候不喜欢在中文和英文之间加空格的人，感情路都走得很辛苦，有七成的比例会在 34 岁的时候跟自己不爱的人结婚，而其余三成的人最后只能把遗产留给自己的猫。毕竟爱情跟书写都需要适时地留白。与大家共勉之。

书写规范的目的是为了提升内容的可读性。书写规范和代码风格很像。主要包括：空格，标点，大小写，专有词的拼写。

推荐阅读：《中文技术文档的写作规范》^[5]。

最后

道理知道的再多，不行动也是白费。所以，赶紧写起来吧~ 我这边准备做个技术写作的微信群，和大伙一起来点亮写作技能。关注本公众号，发消息：“写作”，来加入吧~

参考资料

[1]

SMART 原则: https://baike.baidu.com/item/SMART%E5%8E%9F%E5%88%99/8575850

[2]

GitHub 趋势: https://github.com/trending

[3]

百度指数: https://index.baidu.com/v2/main/index.html#/demand/%E5%89%8D%E7%AB%AF?words=%E5%89%8D%E7%AB%AF

[4]

《金字塔原理》: https://book.douban.com/subject/1020644/

[5]

《中文技术文档的写作规范》: https://www.ruanyifeng.com/blog/2016/10/document_style_guide.html