技术写作的价值

写作并不是一件轻松的事情，特别是技术内容创作，它不仅需要兴趣来驱动，而且需要耐心，所以写作这个活动注定不适合所有人。我想无论是写作、演讲，还是录制视频，除了利益驱动无可厚非之外，大家肯定都有一个额外的共同目的：分享。

至于分享之后为了得到什么，那都不重要，比如我就是为了满足自己的虚荣心，说白了就是装x，看着自己的文章被越来越多的人阅读，越来越多的人认识我，加我微信好友的人越来越多，自己在圈内越来越出名，虚荣心得到了极大的满足。既满足了自己的虚荣心，又造福了广大读者，有何不可呢？

除了我说的这些，写作还有没有其他价值呢？还是拿我亲身经历举例子，我的一部分文章给我带来了全新的工作机会；还有一部分文章吸引了很多社区和团队的目光，主动来和我合作；所有的这一切让我结识了更多志同道合的朋友；当然，获取到大量关注后也给我带来了更多的收入，这个不必避讳。

听了我的描述后，如果你决定开始尝试写点东西，或者已经开始尝试一段时间，但还是没有明确的思路，这篇文章就是为你们准备的。

声明：虽然今天这篇文章是教大家如何写云原生领域的文章，但实际上是通用的，并不局限于云原生，只要你想写作，这篇文章都有一定的参考价值。

写作工具

工欲善其事，必先利其器。既然决定了进入“写作”这个战场，首当其冲的就是选一件称手的兵器，对于写作来说，这个兵器就是“写作工具”。选工具之前，先要明确一下自己偏好的排版格式，目前有两种主流的排版格式：

富文本：富文本格式（Rich Text Format, 一般简称为 RTF）是由微软公司开发的跨平台文档格式。最大的特点是：所见即所得，你把格式调整成什么样子，就会直接显示出什么样的效果。这一点和 Word 类似。目前微信公众号文章就是通过富文本来编辑的。
Markdown：Markdown 是一种轻量的标记语法，你可以理解为一种伪编程语言，和 HTML 有点像，只不过是专门为写作准备的极简格式。Markdown 的语法很简单，只有一些简单的符号，我们只需学习这几个简单的符号，然后插入到写作内容中，不用关心排版。

程序员大多都不喜欢使用 Word 这类富文本编辑器，因为不可控因素太多，各种形式、用法和风格，而且花样繁多，强依赖于编辑器，换个编辑器用法又不一样了。

众望所归的选择还是 Markdown，排版都是可复制的，文字的排版只是多打几个符号而已，最终产出的只是一个纯文本，非常利于传播和迁移。所以 Markdown 才是程序员的最爱。

目前市面上比较流行的 Markdown 编辑器琳琅满目，本文也无法为大家一一介绍，这里只推荐几个我认为最最最优秀的。

Typora

Typora 最吸引人的特性就是它的即时渲染，也就是所谓的所见即所得。一般的 Markdown 编辑器都分为编辑栏和预览栏，Typora 将其合二为一，实时预览，只要你敲入相应的标记符号就立马为你转换为对应的样式，就像写 Word 一样流畅自如。这是本文在 Typora 中的排版样式：

遗憾的是 Typora 目前已经开始收费，但这是合理的，之前 Typora 发布的都是测试版，免费供大家使用，现在正式版开始取消免费，毕竟开发也需要付出，我们要尊重开发者，优质的产品值得付费。我们可以选择不用 Typora，但不必对其收费行为冷嘲热讽。

VS Code

VS Code 虽然是一个代码编辑器，但由于它的功能过于强大，插件过于丰富，扩展性极强，所以人们也常常用它来写作。

Visual Studio Code（简称 VS Code）是一个由微软开发，同时支持 Windows 、 Linux 和 macOS 等操作系统且开放源代码的代码编辑器，它支持测试，并内置了 Git 版本控制功能，同时也具有开发环境功能，例如代码补全（类似于 IntelliSense）、代码片段和代码重构等。该编辑器支持用户个性化配置，例如改变主题颜色、键盘快捷方式等各种属性和参数，同时还在编辑器中内置了扩展程序管理的功能。 ——维基百科

VS Code 借助插件的力量可以实现和 Typora 旗鼓相当的能力。VS Code 默认情况下内置了 Markdown 的预览功能，效果如下：

要想实现即时预览的能力，就需要借助一款强大的插件：Office Viewer。

这货不但可以实时预览编辑 Markdown，还能显示 PDF 文档和 Excel 表格，简直就是简直了。

装好该插件后，需要在内置文件浏览器里依次右键 –> 打开方式，

然后在弹出的面板中选择 Office Viewer。

最终效果如下：

Obsidian

Obsidian 是一个支持双向链接的笔记管理软件，但我们用它来写 Markdown 也是极好的！Obsidian 最新版本也实现了即时预览功能，只需在编辑器设置中将默认的编辑模式改为即时预览即可。

最终呈现的效果如下：

可以看到其实时预览功能目前还有一些小缺陷，比如引用的样式渲染不太理想，不过后续这些问题都会被修复的，现在只是开始。

关于 Obsidian 作为笔记管理软件本身的强大功能，本文不作过多介绍，感兴趣的可以自己研究。

Hackmd

除了个人创作外，有时我们也需要多人协作编辑 Markdown。即使是个人创作，有时也需要请多人帮忙提出改进建议。如果有这方面的需求，可以使用 Hackmd 来协作。在 Hackmd 中，正在编辑这篇文章的人可以同时看见其他协作者正在编辑的位置，编辑一段文字后还可以看见这段文字是谁写的，不同作者用不同颜色表示在这段文字的左边或者下面。还可以对选中的内容通过留言的形式提出改进的建议。

写作类型

笔者目前工作的领域是云原生，更宽泛一点则是基础架构领域，这个领域的技术内容创作类型大概可以分为以下几类：

问题解决类：该类文章以问题为切入点，整篇文章都是围绕着如何解决这个问题，包括问题的前因后果、问题的解决思路与步骤、避坑方法等。比如这篇：Istio 无法访问外部服务的故障排查。
安装部署类：这一类文章比较容易理解，就是记录某个开源项目的安装部署过程。例如这篇：使用 KubeKey 快速离线部署 KubeSphere 集群。
最佳实践类：比安装部署类的文章更加深入，涉及到实际业务的落地，需要根据实际业务来规划架构，众多因素都要考虑在内，比如高可用、弹性伸缩、故障检测、保持连接等等。例如这篇：去哪儿网业务大规模容器化最佳实践。
技术分享类：这类文章纯粹就是为了分享自己学习某个技术的心得体会，比如这篇：KubeSphere 核心架构浅析。
行业趋使观点类：这类文章主要是发表一些个人观点，比如这篇：云原生的 WebAssembly 能取代 Docker 吗？。

还有一些其他的类型我就不列举了，主要就是上面这几类。

写作流程

确定好写作方向后，就可以构思写作内容了。当然了，首先得确定文章主题才能构思内容，没确定文章主题之前是没法提笔就写的。

构思

一篇好的文章主题需要一个好的 Idea，好的 Idea 需要持续积累。我会根据自己平时关注的资讯、读到的文章来确定近期准备写的原创文章主题，如果我读到比较优秀的英文文章，也会把它纳入到翻译的计划之内。俗话说得好，好记性不如烂笔头，不管是原创还是翻译，这些文章主题都要靠记录才能积累下来，你可以记到纸上，也可以记到笔记软件里。我自己就在使用 Obsidian 记录平时积累的写作主题：

大纲

当你决定开始根据某个文章主题动笔写作之前，还有一件重要的事情要做，那就是列出文章的大纲。先列出文章的大纲会让你的写作事半功倍，有了大纲就有了清晰的脉络，层次分明，不会像无头苍蝇一样想到哪写到哪。我一般都是用思维导图的形式来呈现文章的大纲，VS Code 有专门的插件（markmap）可以帮助我们将文章的多级标题转化为思维导图的形式。

或者你也可以直接使用专门的思维导图工具来疏理大纲，比如我使用的是在线版的 processon：

大纲同时也是文章的多级标题，比如我这篇文章的大纲就包含了二级标题和三级标题，一般不建议使用四级标题，除非实在有必要。

文章排版

技术文章的排版有很多需要注意的规范，本文就不一一说明了，感兴趣的可以参考阮一峰的中文技术文档写作规范。

本文只强调几个需要重点注意的事项：

Markdown 的标记语法有多种表示形式，比如无序列表既可以使用 ‘+’ 号，也可以使用 ‘-’、‘*’ 等符号，大家在写作时尽量统一自己的标记语法，如果你想使用 ‘+’ 号，就全部使用 ‘+’ 号，不然看起来会很混乱。
每一个段落之间隔一个空行，尽量避免冗长的段落，如果你的段落内容很长，想办法把它拆分成更多的段落。
标题尽量精减，避免冗长标题。
尽量不要使用四级标题，除非要必要。
二/三/四级标题尽量不要加序号，如果标题很多，可以考虑加序号，但要避免使用非标准格式，比如 01-xxx。
避免冗长的代码段，比如某些命令的输出完全可以省略（yum install）。
每个大标题之间尽量不要使用分割线。
中英文混排时需要在中英文之间插入一个空格，比如：
```
  错误：KubeSphere集群
  正确：KubeSphere 集群
```
为了省去自己手动㪣空格的麻烦，可以借助一些第三方工具来完成。如果你有自己的个人博客，可以使用『赫蹏』这个库，他是专为中文内容展示设计的排版样式增强，基于通行的中文排版规范而来，可自动为你的中英文之间加空格。如果你想在写作时就解决空格的烦恼，搜狗输入法也可以帮你自动加空格，具体的配置方法自己去搜一下，我电脑上没有搜狗输入法，不方便演示。

辅助工具

真正动笔写作的时候，你会发现有很多地方需要借助第三方工具来辅助自己，比如画架构图、截图等等，如果不选择合适的工具来完成这些操作，你可能会举步维艰。

截图

macOS 从 10.14 开始便自带截图 App，只需要按下 Shift-Command-5（或使用启动台）以打开“截屏”就能显示该工具。

功能非常丰富，既可以捕捉整个屏幕，也可以捕捉屏幕的一部分或者之间捕捉特定的窗口，除此之外还可以录制屏幕。

除了自带的截图工具，还有一些第三方的截图工具也很优秀，这里只推荐两个我认为最最最优秀的：

Shottr : 这个截图工具只有 3.2M，运行速度非常快，包含了智能测距、滚动截图、元素智能删除、OCR 文本识别、距离标注等很多别的工具需要付费才提供的功能，支持 Windows。墙裂推荐！
iShot : 和 Shottr 类似，也很强大，比 Shottr 强的地方在于可以手动控制滚动截屏的速度。

文章配图

俗话说得好：一图胜千言。没有配图的文章是枯燥乏味的，尤其是技术文章。好的配图可以帮助读者更轻松地理解文章的内容，增强文章的可读性。大家写技术文章画的最多的配图应该就是架构图了，这方面的画图工具有很多可供选择，还是按照之前的惯例，我只推荐几个特别优秀的。

Omnigraffle : 这是一款非常专业的画图软件，可以画出非常精美的架构图，如果你对架构图的审美要求比较高，推荐使用这个工具。这是我画的关于以 Serverless 的方式实现 Kubernetes 日志告警的架构图：

遗憾的是该软件只有 macOS 版本，Windows 用户只能另寻他路了。
diagrams.net : 之前叫 draw.io，现在改名了。这是一个在线的画图工具，非常强大，内置了各种常用的元素和图标。除了网页版之外，还有一个开源的桌面客户端，支持 macOS、Windows 和 Linux 平台，客户端项目地址：https://github.com/jgraph/drawio-desktop。
Cloudcraft : 如果你更倾向于炫酷的三维架构图，可以选择使用 Cloudcraft，只不过内置的三维图标有点少哦。

图床

无论是截图还是自己画的图，最终都要上传到某个地方然后提供一个外网可以直接访问的链接，这个用来存图片的地方就叫做『图床』。

目前网上免费的图床太多了，最知名的应该就是 sm.ms 了，登录用户有 5GB 的免费空间，个人用几年足矣。不过服务器不在国内，访问速度不太行。

除了免费的图床之外，还有一些本身不是图床的平台也可以拿来当图床用，比如 GitHub。。新建个专门的仓库用来存图片，简直不要太香。如果嫌速度慢，可以使用著名的 CDN jsDelivr 来反代，到国内速度贼快，国内线路走的是 CDN 提供商网宿。推荐使用这个 Github 增强油猴脚本，可以直接显示 GitHub 文件的各个加速 CDN 的链接。

但是很遗憾，去年年底 jsDelivr 在国内的域名备案被吊销了，导致国内 CDN 提供商网宿移除了 jsDelivr 的账号，就是因为滥用的人太多，羊毛薅得太狠了。现在 jsDelivr 到国内的速度也没啥优势了，比 GitHub 也没强多少。

最靠谱的方式还是得花钱，把图片存到对象存储中，比如阿里的 OSS 之类的，也花不了几个钱。

图片管理

选择了适合自己的图床后，还要考虑到『上传和管理图片』这个老大难问题。你想想，假设我使用 GitHub 作为图床，我要上传一张图片，就需要先 commit，然后 push，然后再打开仓库复制这张图片的链接，最后再插入到 Markdown 中，想想都能吐血。

能不能快一点，从上传图片开始到最后将图片插入到 Markdown 中不超过 5 秒钟，能不能做到？当然可以，前辈们早就想到了这个问题，并产出了优秀的图片上传管理工具。这里只推荐两款：

PicGo : PicGo 支持全平台，开源且免费，支持丰富的插件系统，推荐使用。使用 PicGo 上传图片的流程是这样的：先复制图片，然后通过一个快捷键上传图片到对应的图床（并直接返回一个该图片的直链到你的系统剪切板），此时你只需到你的 Markdown 内容中粘贴就完事了，整个过程不超过 5 秒钟。
uPic : uPic 只支持 macOS 平台，使用体验比 PicGo 更好，推荐 macOS 用户使用。

文章格式化

如果文章写完后你发现有很多中英文之间没加空格，你是不是还得回过头去一个一个加空格？别担心，这个问题也有专门的工具来解决。先推荐一款开源的优化排版工具 HeySpace，这是一个使用 Go 语言编写的命令行工具，核心功能是在中英文之间添加空格，除此之外还可以去除连续两个以上的空行，感兴趣可以自己试用。

再推荐一款公众号在线排版网站墨滴，可以将 Markdown 转换为富文本，然后直接粘贴到公众号的编辑器中。虽然这是一款公众号排版工具，但我们可以利用它的部分功能来实现格式化的目的，只需将 Markdown 内容粘贴到编辑器中，然后点击『格式化文档』即可。

写在最后

以上就是我关于如何进行技术内容创作的经验之谈，从写作对个人的价值谈到技术内容的创作选型，再到文章的排版和辅助工具，希望能帮助大家开启自己的技术内容创作之路。当然，其中肯定有考虑不周之处，望海涵，也欢迎补充更好的建议。