写作

概述

参考
GitHub 项目，ruanyf/document-style-guide中文技术文档写作规范

写作技巧

原文链接：https://mp.weixin.qq.com/s/I38Wr-CGEbaMrT-xj3QZ8A

技术写作的价值

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

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

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

写作工具

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

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

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

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

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

Obsidian

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

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

Obsidian

Typora

https://www.typora.io/

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

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

Typedown

Typora 平替，微软商店可直接安装

https://apps.microsoft.com/store/detail/typedown-%E8%BD%BB%E9%87%8F%E7%BA%A7-markdown-%E7%BC%96%E8%BE%91%E5%99%A8/9P8TCW4H2HB4

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。

Hackmd

https://hackmd.io/

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

输入法

2024 年 4 月 17 日，搜狗自动右下角广告弹窗，卸载

2024 年 4 月 18 日，讯飞输入法无法配置 ` 符号与 · 符号，就是说无法在中文环境下输入出来 ` 符号。

不过卸载体验很好，${APPDAT} 目录中的讯飞程序相关的数据在机器重启后，会自动清理了。

写作类型

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

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

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

写作流程

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

构思

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

大纲

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

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

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

文章排版

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

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

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

辅助工具

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

截图

macOS 从 10.14 开始便自带截图 App，只需要按下 Shift-Command-5（或使用启动台）以打开“截屏”就能显示该工具。功能非常丰富，既可以捕捉整个屏幕，也可以捕捉屏幕的一部分或者之间捕捉特定的窗口，除此之外还可以录制屏幕。

除了自带的截图工具，还有一些第三方的截图工具也很优秀

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

文章配图

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

excalidraw.com # 一款开源的虚拟手绘风格白板。
- https://github.com/excalidraw/excalidraw
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 也没强多少。

最靠谱的方式还是得花钱，把图片存到对象存储中，比如 {阿里,华为,etc.} 的 OSS 之类的，40 G 一年 9 块钱。

图片管理

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

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

PicGo

参考：
GitHub 项目，Molunerfinn/PicGo
GitHub 项目，PicGo/Awesome-PicGo 使用 PicGo 的一系列很棒的项目，包括插件和二次开发的产品。

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

PicGo关联文件与配置

运行时与配置保存路径

Windows

%APPDATA%/picgo/ # 运行时数据保存路径
- ./data.json # 配置文件

Linux 下只有基础目录与 Windows 不同，基础目录下的文件和目录都一样

$XDG_CONFIG_HOME/picgo/ 或者 ~/.config/picgo/ # 运行时数据保存路径

PicList

参考：
GitHub 项目，Kuingsmile/PicList

基于PicGo的二次开发版本，增加了云存储管理和相册云端同步删除功能

uPic

uPic 只支持 macOS 平台，使用体验比 PicGo 更好，推荐 macOS 用户使用。

文章格式化

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

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