# 浅谈程序员如何写作

> Site index: <https://blog.suxiong.me/llms.txt>

Original: [浅谈程序员如何写作](https://blog.suxiong.me/blog/how-to-write-as-a-developer)

Author: Suxiong

Date: 2023-08-13

从写作平台选择、内容方向、选题方法等多个维度，深入探讨程序员如何进行技术写作。文章详细介绍了各类写作平台的特点，以及如何选择合适的写作方向和选题，帮助程序员更好地进行技术分享和知识传播。

Tags: 技术写作 / 内容创作 / 知识分享 / 个人成长

## 前言

写作是我为数不多且长期坚持的爱好。大学期间，成为校党委宣传部学生助理并加入校记者团后，便开始与写作打交道。如果google我的名字，能够搜索到一些在大学期间写的公众号文章。毕业后，在浪潮期间，主要在知乎和csdn上发布技术文章，同时收获了一些不错的访问量和点赞。

**csdn平台数据**

**知乎平台数据**

短暂的阿里工作期间，在内部知识分享平台ATA发布了两篇技术文章，一篇关于Rxjs，一篇关于React useEffect hook，也收获了10个赞左右。

加入花旗后，在自建网站上发布了几篇职业生涯思考与学习笔记相关文章。

这么多年下来，写作对我来说就是刻意练习，强迫自己思考，复盘。那么程序员该如何写作，我总结了以下心得体会。

## 选择合适的写作平台

### 公共还是自建

按照归属权划分，写作平台归为两个类型——公共平台和自建平台。

- 公共平台是指官方将写作工具到发布展示提前为创作者搭建完成，创作者只需要注册账号就可使用，非常便捷。比如掘金，知乎，微信公众号等。
- 自建平台是指创作者自己搭建写作与发布平台，从服务器到网站源码，所有权限都在自己手中。

还有一些平台比较有趣，属于公共平台上的自建平台，比如GitHub博客，我也将其归为自建平台，优点是免费不要钱，逼格高。

### 浅谈公共平台

公共平台最大优势并不是使用便捷，而是平台本身。比方说微信公众号有社交关系，头条有流量推送，掘金有社区氛围，平台的力量能够让创作者更专注于创作，不至于所创作的优质内容无人问津。

但是由于公共平台需要保证发布内容健康，所以限制非常多，多到让人无语。这便是为何奇怪的拼音缩写层出不穷的原因，有些词你感觉会限流，但又不确定，安全起见，就用字母代替。但这也都是被逼出来的。因为网警真的会电话上门，要求删除某些内容。出问题的是一段看起来很普通的话，一搜索，才明白这个词原来指的是……不能说不能说。

下面对于几个主流公共平台进行分析。

#### 微信公众号

优点：

1. 强大的社交属性优势

缺点：

1. 封闭的微信生态。除了微信本身，唯一入口应该是搜狗搜索，但是搜狗搜索发展并不给力。
2. 微信活跃人数增长已到顶峰。

建议：

每发布一篇技术文章，可转发到朋友圈引流。

#### 头条号

优点：

1. 优秀的推荐算法

缺点：

1. 头条号以资讯信息为主，讲求短平快，因此深奥的技术文章不适合这里。

建议：

技术咨询、圈子八卦、吐槽与点评，那种看一眼好像学会了，但实际上并没学到的技术在这个平台上最吃香。

#### 百家号

优点：

1. 百度搜索引擎的倾向性

缺点：

1. 限制极多，审核极严。早先百度为了扶持百家号，搜索结果严重向百家号倾斜，哪怕文不对题、注水内容，也会出现在搜索结果前列，以至于出现《搜索引擎百度已死》的名作，因此之后只能对内容严苛要求，各种限制。

建议：

可以抢占流行技术或者即将流行的技术关键词，借助百度搜索引擎的倾向性，增加在下沉技术群体中的影响力。

#### 掘金

社区氛围良好，编辑负责，背靠字节不差钱，不用担心倒闭。

另外，如果精力允许，在掘金发布的技术文章也可以在 segmentfault、infoQ 等平台同步，都是专业社区，多点人关注总是好的。

#### 知乎

作为一个问答型网站，本身就是知识学习的，和我们的技术写作的精神世界是契合的，因此，专业的知识文章在这里是有其生存空间的。

加上知乎被百度投资，在搜索引擎排名上有较高的权重，因此，在知乎写技术文章也是个不错的选择，会有很好的长尾效应。

#### B站

根据我的观察，B 站专栏在谷歌和百度的权重都还可以，优质内容有被挖掘出来的机会。

不过B 站专栏的编辑器对于技术类文章的排版和发布很不友好。如果时间充裕，做技术类视频分享也是一个不错的选择。

#### CSDN、博客园等

一方面由于历史久远，无人维护，所以产品体验比较差。另一方面这些网站盗版横行，无法无天。不过，不得不承认，这些网站在百度搜索引擎中的排名是真的高，可能是气味相投吧。

所以，平常的工作流水账，bug 解决记录等这些没有营养但可能有用的东西，就可以往这些地方倒。专业社区放精品，流氓老站喂糠饼，大家都有美好的未来。

### 浅谈自建平台

自建平台最大的优点便是自由，这里不仅是文字的自由，还有形式的自由。

在自建平台上，可以正常书写，哪怕很隐晦地开车，无需担心审核不通过，谁叫管理员就是你自己。同样自建平台可以任意在正文中插入任意的css和javascript代码，可以任意定制文章和排版的样式。

有人会问，"那是选择自建平台还是公共平台呢？"。小孩才做选择，成年人当然全都要。我们可以在自建平台首发，公共平台引流，活用各自的优点，岂不美哉。

下面对于自建平台进行分析。

#### 完全自建平台

如果你的野心很大，决心很强，规划很远，则可以考虑完全自建平台，否则，一点也不推荐。

两点原因：

1. **备案困难**

目前网站备案政策直接摁死了个人开发者，以上海的政策举例，个人备案首先需要上海的居住证，其次，网站不能是交互式网站，必须是纯静态展示的。

作为一个技术写作平台，最基本的评论模块肯定是要有的，但是不行，只要你的网站可以评论，哪怕使用的是第三方评论组件，都认为是交互式网站，无法备案。

既然个人备案行不通，那我注册个公司，可以吗？理论上是可以的，但实际操作起来，成本超乎想象。

首先是钱财，公司每个月都需要给银行账户年费，一年最少 3000 块。

其实钱还好，关键是极其麻烦。备案的时候，网安要求上门交材料，还要查看你的管理员账号，确认有没有下载公安部提供的敏感关键词库，他会测试你的网站输入涉黄涉爆的敏感词是否正常显示。

如果你备案成功了，还要加一个群，网警会定期让你提交一些东西，排查不良信息。

如果是正规的互联网公司，这种事情可以交给运维来做。但是，如果你申请公司就是为了备案，那确实会让人崩溃？

所以，大家如果要自建平台，直接购买海外服务器即可，无需备案，只要遵纪守法，没人管你的，无非就是网速慢一点。

2. **没有流量**

个人自建站点由于没有平台的优势，因此，流量只能看天吃饭，这个"天"就是搜索引擎，可惜现在的百度已经不是当年的百度了，谷歌因为政策的原因无法使用，搜狗始终半死不活，必应相对来说好用一些。

在 2018 年之前，百度虽然有一些医疗广告，但还是可以搜索到一些优质的中小网站，里面会有很多不错内容，还算客观中立。

但是，2018 年，百度为了扶持自家的熊掌号和百家号（前者已经凉凉），将原本应该给优质中小网站的流量全部引到了自家产品中。因此当时死了一大批网站，知乎也因为这个策略变动导致 PC 端流量暴跌了七成，一直到第二年百度入股知乎才好转。

#### 半自建平台

完全自建平台费时费力，因此半自建平台是一个非常不错的选择。

目前有很多成熟优秀的开源静态站点生成工具，以下是我接触过的，很好用的开源静态站点生成工具。

- [Vuepress](https://vuepress.vuejs.org/)
- [Vitepress](https://vitepress.vuejs.org/)
- [Docusaurus](https://www.docusaurus.io/)
- [Eleventy](https://www.11ty.dev/)
- [Astro](https://astro.build/)
- [GatsbyJS](https://www.gatsbyjs.com/)
- [Hugo](https://gohugo.io/)

### 小结

时代在变，现在要想通过写作名利双收，一定离不开平台的力量，单打独斗实在太难了。

我们可以在半自建平台上首发，然后分享至朋友圈，并且发布在多个公共平台上进行引流。

比较专业的，稀缺的，有质量的文章建议在掘金、思否、知乎等这类偏专业的平台发布，可以有效地利用长尾流量。

浅阅读的、偏资讯的技术文章建议在公众号、头条号和百家号等平台发布，可以有效地利用社交流量和算法流量在短期内爆发性增长。

## 该写什么？

我经常会面对一个议题或者一个问题大脑一片空白。此时空想无益，应该脚踏实地，收集碎片信息，取笔落纸，归纳，梳理与汇总，整个线条就会逐渐清晰。这就是解决开放性问题的方法论，也是我的经验技巧。所以技术写作该写什么？首先，我们需要确定写作的方向，确定好方向后，再在其中确定适合自己的选题，选题确定好之后就可以进入细节和技巧层面。

### 确定写作方向

关于写作方向，我的建议是这样的。

#### 与本职工作相关

首先，写作的内容是自己熟悉擅长的领域，不容易翻车。

其次，写作对于技术的学习很有帮助，会形成对事业有帮助的正反馈，从而更容易坚持下去。

#### 专注于垂直领域

例如，前端开发就是一个分支特别多的职业，有用户体验和无障碍方向、Node.js方向、小程序快应用开发方向、svg/canvas/webgl动效创意表现方向、数据可视化方向、低代码方向等等。

普通人无法所有方向面面俱到，所以，如果每个技术方向都插上一脚，写上一篇，那必然是泛泛而谈的一篇文章。

中国互联网发展已经二十多年了，行业发展日趋成熟，职业分工愈发细化，从业人员众多，根本不缺入门的学习资料。

所以，写作的目的要么为了个人成长，要么为了脱颖而出，精力有限，时间有限，所以一定要专注在某个垂直领域，让自己的付出价值最大化。

### 确定写作选题

我大致将技术写作选题分为以下八类：

1. 新方法、新特性、新技术
2. 框架、工具、会议体验指南
3. 外文翻译
4. 技术实现方案综述、技术选型对比
5. 日常工作中的小技巧、小创新
6. 深入理解xxx，xxx原理剖析
7. 体现技术深度的棘手问题解决
8. 技术资讯与技术人文

- 第1、2、3选题并不需要精深的技术，因为不涉及技术实操。
- 第4选题也不需要多么精深的技术，但是对技术广度有一定要求。这类选题有固定的写作套路：打开搜索引擎，搜索某个技术点，打开七八篇不同的文章，取其精华去其糟粕，使用自己的语言整合输出，最后附上参考文章。此类文章有别于资源合集类文章，比如"BAT最新面试题合集"、"前端面试合集"之类的文章。此类文章仅有苦力价值在其中，别人会稀罕这篇文章，但不会稀罕你这个人，可以收获流量，但是无法收获影响力，因为好人卡并不属于影响力。
- 第5、6、7选题一定要多些，收益斐然！对于技术写作而言，技术能力就是核心优势。如果你是一个技术牛人，深度和广度兼有，那恭喜你，只要愿意花时间和精力去写作，收获斐然。因为专业领域写作者是稀少的，而通俗领域的写作者是泛滥的，物以稀为贵。
- 第8选题属于典型浅阅读内容写作，这类文章特别适合在流量平台传播。

### 确定写作内容

#### 参考文档

前端发展很快，各种新特性层出不穷，每一个新特性其实都是一篇值得书写的文章，那么如何跟踪这些新特性？我推荐三个不错的网站：

1. <https://caniuse.com/>
2. <https://developer.mozilla.org/en-US/docs/Glossary>
3. <https://developer.mozilla.org/en-US/docs/Web/API>

我们可以找到自己关注的垂直领域，寻找哪些特性是自己不知道，但却非常有用的，去研究它，并把研究结论写出来。既得到了学习，又输出了文章，一举两得。

#### 固定素材

有些写作素材会定期出现，比如知名框架或知名工具的新版发布。比如最近vite 4.0发布了，便可以抢占先机，搞一波原创文章出来，保证转发量极大。如果最热门的赶不上，那就发布次热门的。别人发Chrome，你就发Safari，别人发Deno，你就发Bun。东边不亮西边亮，黑了南方有北方。

#### 订阅周刊

无论国内还是国外，都有专门周刊性质的技术写作。周刊成本主要在于收集聚合。同样，周刊也是分类别的，有的是资讯周刊，有的是好文推荐，有的是二者混合。

如果是硬核技术类周刊，优先关注国外的周刊。据我观察，国外一项技术兴起，到国内完全流行，会有一年左右的时差。因此，关注国外的周刊所获得的信息往往会领先别人一步。

周刊推荐：

1. 奇舞周刊
2. 前端早读课
3. 阮一峰的网络日志
4. [React Digest](https://reactdigest.net/?utm_source=programming\&utm_medium=web\&utm_campaign=footer)
5. [Daily Tech](https://dailytech.email/?utm_source=programming\&utm_medium=web\&utm_campaign=footer)
6. [Tech Lead Digest](https://techleaddigest.net/?utm_source=programming\&utm_medium=web\&utm_campaign=footer)

#### 工作实践

很多人觉得自己在项目中没有使用多么牛逼的技术，做出多么杰出的贡献，并没有什么好讲的，但并不是这样。反问自己：

**这个项目始终一帆风顺，没遇到任何困难吗？**

在日常开发中，我们肯定会遇到解决问题卡壳的情况，我将其分为四类：启动错误，复杂逻辑，技术细节，大意马虎。除了大意马虎之外的其他问题都可以作为写作的内容。

|       | 启动错误              | 复杂逻辑                  | 技术细节             | 写作平台    |
| ----- | ----------------- | --------------------- | ---------------- | ------- |
| 日常写作  | 如实记录什么错误，怎么解决     | 自己的实现策略               | 哪里写错了            | 非运营平台   |
| 高要求写作 | 进一步分析背后的原因，如何再次避免 | 起因、思考、过程、问题、解决及结果完整闭环 | 深入技术细节分析原因，再举一反三 | 专业社区主账号 |

若问题出现是因为操作失误或者大意马虎导致的，则适合快速记录。此类文章适合发布在CSDN、简书这些无心运营，同时可以吃搜索引擎流量的非主力帐号上。

有两个好处：

1. 之后遇到类似的问题，有地方溯源，看看之前是怎么解决的。
2. 帮助遇到此类问题的人，有时会有意想不到的流量。

**这个项目有没有用过以前没用过的技术或者实现方式？**

如果发现新做的项目使用的代码和技术和之前的项目是一样的，那就需要引起警觉了，你可能进入了一年工作经验三年用的糟糕状态中，需要及时调整。

1. 抓紧时间拓展自己的知识广度，增加专业积累，很多时候没有创新和变化是因为并不知道同样的东西还有更多更好的实现方式。
2. 适当勇敢一点，一点一点地尝试自己没用过的东西。比如，循环可以使用原始的for语句，也可以使用foreach之类的方法。
3. 如果因为项目性质导致自己就是个流水线上的搬运工，则可以向上反馈，尽量申请去其他项目组里进行活水。

**这个项目有没有引用外部的组件或者工具？**

如今前端开发，基本都会使用框架和UI组件库。那么是不是可以对这些框架和工具进行点评呢？在使用的过程中肯定有不爽或不足的地方，比如某UI组件库不支持某能力，你是怎么处理的？魔改还是曲线救国。无论怎么解决，都是优质的写作内容。

**这个项目做完之后自己有成长吗？**

我们需要经常思考我在这个项目中究竟得到了什么成长。这个成长不一定是技术上，也可以是知道了如何更好地沟通和交流，也可以对产品设计和项目管理的理解更深刻。

如果是长足进步，则一篇雄文蓄势待发。如果只是微小的进步，也没关系，可以作为项目总结的点睛之笔。

## 如何给文章起标题

就写作而言，内容为王，但配上合适的标题，确实会提高文章曝光度。

文章的性质决定了文章的访问来源，也就决定了标题的倾向性。文章的访问来源主要分为两种，一个是平台的信息流推荐，另外一个就是搜索引擎。

就平台信息流推荐而言。比如，我写的是职场故事，那基本不可能被搜索引擎搜索到，因为这个世界上的职场故事太多了，不可能轮到我这一个。那此时我的文章标题应该尽可能地吸引人的注意力，而不用考虑搜索引擎。人类普遍感兴趣的东西都是类似的，八卦、钱、异性。所以，职场故事标题尽可能围绕这几个东西展开。就技术文章来讲，则尽可能出现动作、数字、吸睛词（即热点、流行事物），句式上可以疑问、感叹，但注意语气不要太强烈，技术群体的读者都比较理性，不吃这一套。

如果希望自己的文章流量尽可能多的来自搜索引擎， 则需要在创建标题时多想想：用户如果想了解我文章中的知识，可能会搜索什么关键字，然后想办法在标题中体现。

## 如何搭建文章的框架结构

### 核心思想

写作核心思想无非两个：一是文字前后连贯。二是内容重点突出。

#### 连贯性

**文字层面**

文字层面的连贯性主要通过关联词保证。分为八大类：并列、承接、递进、选择、转折、因果、假设和条件。该方面比较基础，不过多展开。

**框架层面**

框架层面的连贯，一种是通过结构设计实现，另外一种就是使用承上启下的语句强制连贯。

就结构设计而言，最典型具有连贯性的事物就是时间。当然具有连贯性的事物还有很多，比如数字一二三，方位上中下，从头到尾，从理论到实践等，都可以作为我们设计文章框架结构等理论依据。

就强制连贯而言，其常出现在上下文内容偏差较大，风格不一，明显不连贯的场景下。常见的语言描述如下：

- 上面讲的是ABC，下面再讲甲乙丙……
- 扯远了，回到正题……
- ……

很好理解，我就不举例说明了。个人感觉最好的强制中断，就是"分割线"。

#### 突出性

如何表达突出性，那便是学会让文章脉络清晰，重点突出。

**脉络清晰**

如何使文章脉络清晰，那便是采用基于标题自动生成的目录树。但有一个问题就是移动端并不支持目录树，因此可以在文章顶部建一个目录树，并且增加点击定位的功能。

**重点突出**

实现起来其实也很简单：

1. 要点标题需体现；
2. 亮点位置可靠前；
3. 重点篇幅不设限；

### 具体写作套路

#### 技术科普

此类文章人人都可以创作，并且适合新人阅读，受众广泛。

#### 原理剖析

此类文章对于创作者加深对当前技术的理解很有帮助，但是受众不一定广泛。

#### 功能实现

此类文章是搜索引擎流量来源大户。很多开发者在实现某一个功能时，都习惯先找找有没有现成的代码可以直接使用。

#### 使用教程

在我的认知中，使用教程就是针对小白的奶妈式文章。

#### 问题解决

#### 项目总结

#### 会议记录

其实各个城市还有不少免费的技术沙龙，各个技术社区也会有一些免费的线上活动，一些知名行业从业者也会不定期直播，因此，只要你有兴趣，都可以作为观众参与其中。参加完了，是不是可以写篇文章记录下呢？

这种文章不需要技术含量，但是访问量相当的高，因为人都是懒惰的，总希望以最低的成本收获最多的东西。

#### 工具测评

#### 技术人文

技术人文所包含的写作范围非常广泛，例如软技能分享、心理困惑答疑、职业发展指导、行业发展看法等都属于技术人文的写作范畴，而不同的主题所需要的框架结构都是不一样的。但是也可以找到可鉴见的讨论。

#### 职场故事

通常都是当事人的真实经历，是比较好写的，按照时间线讲好每个时间段的故事即可，如果分享的是刚编的故事，也可以遵循这个套路。

## 如何制作配图及相关要素

技术写作能够使用合适的素材将文章质量变得更好。素材主要分为四类：

1. 代码片段
2. 辅助图片
3. 演示gif
4. 在线案例

### 代码片段

其实比较基础，但需要注意两点。

1. 优先使用代码块功能
2. 代码务必要精简

### 辅助图片

技术文章配图大致分为三类：示意图、表情图和视觉图。

#### 示意图

示意图是技术文章中最重要也是最常见的配图，并且多以截图和线框图为主。

**截图**在os系统中，可以使用[Xnip](https://zh.xnipapp.com/)这个截图工具，还是比较不错的。

**线框图**无论绘制流程图还是逻辑图，无可争议，最好用的一定是[FigJam](http://figjam.new/)，它是Figma中使用的白板协作工具。我也有用过[iodraw](https://www.iodraw.com/diagram/)，这个工具也不错。

#### 表情包

表情包属于锦上添花，目的是传达情绪，营造氛围。所以需要注意的是：一是表情包图片一定不要多；二是谨慎使用gif表情包。

#### 视觉图

视觉图主要是文章的封面图，主要注意的是版权问题。我经常在[pixabay](https://pixabay.com/zh/)这类免费网站下载。

### 演示gif

在os系统中，我主要是用[GIPHY CAPTURE](https://giphy.com/apps/giphycapture)软件进行录屏gif。

### 在线案例

这里推荐几个适合在线演示的网站：

1. [codepen](https://codepen.io/trending)。主要用于偏视觉、偏交互效果的在线演示。
2. [jsbin](https://jsbin.com/?html,output)。主要用于js代码运行，并且本身就是纯开源项目，适合零成本搭建在自己的平台或者公司内部。
3. [codesandbox](https://codesandbox.io/)。主要适用于运行代码依赖于框架或环境。
4. [runkit](https://runkit.com/home)。主要适用于node.js运行。

## 防盗小技巧

### 版权声明

在文章的头部和尾部放上版权声明还原本地址，很多盗版网站都是直接抓取内容的，会把版权声明信息一起带过去，此时，可以带来一定的访问回流。

### 图片水印

文章中的配图可以打上独家水印，这个无需每一张图片都打，选几张就足够了。

### 内容植入

辅助图片与在线案例中尽量加入与自己相关的内容。并且，写作时也可以多多引用自己之前的文章。

## 结尾

写作这类事情缺乏短期刺激，无法及时带来满足感和愉悦感，其实很难坚持下去。我觉得应该告别苦尽甘来的叙事心理。其实仔细想想，自己也并不是按照苦尽甘来这套叙事方式成长的。正确做法一定是：苦甘并存，螺旋上升。也就是我们在经历辛苦的同时，一定要想办法及时填补快乐。但行好事，莫问前程。无论是做事还是人生，才会走得更长更远。

最后，互联网作为一个新兴行业，在我看来还是相对公平的一个行业，只要勤奋有能力，就会获得与自身相匹配的收益。所以，要相信自己能够成功，相信阳光就在风雨后，相信天道酬勤，加油吧！