作为一名成熟的云原生布道师,我是这么写作的

语言: CN / TW / HK

技术写作的价值

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

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

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

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

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

写作工具

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

  • 富文本:富文本格式(Rich Text Format, 一般简称为 RTF)是由微软公司开发的跨平台文档格式。最大的特点是: 所见即所得 ,你把格式调整成什么样子,就会直接显示出什么样的效果。这一点和 Word 类似。目前微信公众号文章就是通过富文本来编辑的。

  • Markdown:Markdown 是一种轻量的标记语法,你可以理解为一种伪编程语言,和 HTML 有点像,只不过是专门为写作准备的极简格式。Markdown 的语法很简单,只有一些简单的符号,我们只需学习这几个简单的符号,然后插入到写作内容中,不用关心排版。

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

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

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

Typora

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

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

VS Code

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

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 [3] 是一个支持双向链接的笔记管理软件,但我们用它来写 Markdown 也是极好的!Obsidian 最新版本也实现了即时预览功能,只需在编辑器设置中将默认的编辑模式改为即时预览即可。

最终呈现的效果如下:

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

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

Hackmd

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

写作类型

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

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

写作流程

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

构思

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

大纲

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

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

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

文章排版

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

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

  • Markdown 的标记语法有多种表示形式,比如无序列表既可以使用 '+' 号,也可以使用 '-'、'*' 等符号,大家在写作时尽量统一自己的标记语法,如果你想使用 '+' 号,就全部使用 '+' 号,不然看起来会很混乱。

  • 每一个段落之间隔一个 空行 ,尽量避免冗长的段落,如果你的段落内容很长,想办法把它拆分成更多的段落。

  • 中英文混排时需要在中英文之间插入一个空格,比如:

    错误:KubeSphere集群
    正确:KubeSphere 集群

    为了省去自己手动㪣空格的麻烦,可以借助一些第三方工具来完成。如果你有自己的个人博客,可以使用 『 赫蹏 [8] 』这个库,他是专为中文内容展示设计的排版样式增强,基于通行的中文排版规范而来,可自动为你的中英文之间加空格。如果你想在写作时就解决空格的烦恼,搜狗输入法也可以帮你自动加空格,具体的配置方法自己去搜一下,我电脑上没有搜狗输入法,不方便演示。

辅助工具

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

截图

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

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

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

  • Shottr [9] : 这个截图工具只有 3.2M,运行速度非常快,包含了智能测距、滚动截图、元素智能删除、OCR 文本识别、距离标注等很多别的工具需要付费才提供的功能,支持 Windows。墙裂推荐!

  • iShot [10] : 和 Shottr 类似,也很强大,比 Shottr 强的地方在于可以手动控制滚动截屏的速度。

文章配图

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

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

    遗憾的是该软件只有 macOS 版本,Windows 用户只能另寻他路了。

  • diagrams.net [12] : 之前叫 draw.io,现在改名了。这是一个在线的画图工具,非常强大,内置了各种常用的元素和图标。除了网页版之外,还有一个开源的桌面客户端,支持 macOS、Windows 和 Linux 平台,客户端项目地址: https://github.com/jgraph/drawio-desktop

  • Cloudcraft [13] : 如果你更倾向于炫酷的三维架构图,可以选择使用 Cloudcraft,只不过内置的三维图标有点少哦。

图床

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

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

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

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

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

图片管理

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

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

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

  • uPic [19] : uPic 只支持 macOS 平台,使用体验比 PicGo 更好,推荐 macOS 用户使用。

文章格式化

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

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

写在最后

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

引用链接

[1]

Typora: https://www.typora.io/

[2]

VS Code: https://code.visualstudio.com/

[3]

Obsidian: https://obsidian.md/

[4]

Hackmd: https://hackmd.io/

[5]

markmap: https://github.com/gera2ld/markmap-vscode

[6]

processon: https://www.processon.com/i/564c654de4b02cebc6408721

[7]

中文技术文档写作规范: https://github.com/ruanyf/document-style-guide

[8]

赫蹏: https://github.com/sivan/heti

[9]

Shottr: https://shottr.cc/

[10]

iShot: https://apps.apple.com/cn/app/ishot-%E6%88%AA%E5%9B%BE-%E9%95%BF%E6%88%AA%E5%9B%BE-%E6%A0%87%E6%B3%A8%E5%B7%A5%E5%85%B7/id1485844094

[11]

Omnigraffle: https://www.omnigroup.com/omnigraffle

[12]

diagrams.net: https://app.diagrams.net

[13]

Cloudcraft: https://app.cloudcraft.co

[14]

sm.ms: https://sm.ms/

[15]

jsDelivr: https://www.jsdelivr.com

[16]

网宿: https://www.wangsu.com/

[17]

Github 增强油猴脚本: https://greasyfork.org/zh-CN/scripts/412245-github-%E5%A2%9E%E5%BC%BA-%E9%AB%98%E9%80%9F%E4%B8%8B%E8%BD%BD

[18]

PicGo: https://github.com/Molunerfinn/PicGo/

[19]

uPic: https://github.com/gee1k/uPic

[20]

HeySpace: https://github.com/louisun/HeySpace

[21]

墨滴: https://www.mdnice.com/

KubeSphere (https://kubesphere.io)是在 Kubernetes 之上构建的 开源容器混合云 ,提供全栈的 IT 自动化运维的能力,简化企业的 DevOps 工作流。

KubeSphere 已被  Aqara 智能家居、爱立信、本来生活、东软、华云、新浪、三一重工、华夏银行、四川航空、国药集团、微众银行、杭州数跑科技、紫金保险、去哪儿网、中通、中国人民银行、中国银行、中国人保寿险、中国太平保险、中国移动、中国联通、中国电信、天翼云、中移金科、Radore、ZaloPay  等海内外数千家企业采用。KubeSphere 提供了开发者友好的向导式操作界面和丰富的企业级功能,包括  Kubernetes   多云与多集群管理、DevOps (CI/CD)、应用生命周期管理、边缘计算、微服务治理 (Service Mesh)、多租户管理、可观测性、存储与网络管理、GPU support  等功能,帮助企业快速构建一个强大和功能丰富的容器云平台。

 :sparkles: GitHub :https://github.com/kubesphere

 :computer: 官网(中国站) :https://kubesphere.com.cn

:man:‍:computer:‍  微信群: 请搜索添加群助手微信号  kubesphere

 :link: 企业服务 https://kubespher e.cloud