作为一名成熟的云原生布道师,我是这么写作的
![](http://mdimg.wxwenku.com/getimg/356ed03bdc643f9448b3f6485edc229b24a65c10ccfd446d6de3b1d832bd6e23572217ce671de43e307a79a2e6ec21bc.jpg)
技术写作的价值
写作并不是一件轻松的事情,特别是技术内容创作,它不仅需要兴趣来驱动,而且需要耐心,所以写作这个活动注定不适合所有人。我想无论是写作、演讲,还是录制视频,除了利益驱动无可厚非之外,大家肯定 都有一个额外的共同目的:分享 。
至于分享之后为了得到什么,那都不重要,比如我就是为了满足自己的虚荣心,说白了就是装x,看着自己的文章被越来越多的人阅读,越来越多的人认识我,加我微信好友的人越来越多,自己在圈内越来越出名,虚荣心得到了极大的满足。既满足了自己的虚荣心,又造福了广大读者,有何不可呢?
除了我说的这些,写作还有没有其他价值呢?还是拿我亲身经历举例子,我的一部分文章给我带来了全新的工作机会;还有一部分文章吸引了很多社区和团队的目光,主动来和我合作;所有的这一切让我结识了更多志同道合的朋友;当然,获取到大量关注后也给我带来了更多的收入,这个不必避讳。
听了我的描述后,如果你决定开始尝试写点东西,或者已经开始尝试一段时间,但还是没有明确的思路,这篇文章就是为你们准备的。
声明:虽然今天这篇文章是教大家如何写云原生领域的文章,但实际上是通用的,并不局限于云原生,只要你想写作,这篇文章都有一定的参考价值。
写作工具
工欲善其事,必先利其器。既然决定了进入“写作”这个战场,首当其冲的就是选一件称手的兵器,对于写作来说,这个兵器就是“写作工具”。选工具之前,先要明确一下自己偏好的排版格式,目前有两种主流的排版格式:
-
富文本:富文本格式(Rich Text Format, 一般简称为 RTF)是由微软公司开发的跨平台文档格式。最大的特点是: 所见即所得 ,你把格式调整成什么样子,就会直接显示出什么样的效果。这一点和 Word 类似。目前微信公众号文章就是通过富文本来编辑的。
-
Markdown:Markdown 是一种轻量的标记语法,你可以理解为一种伪编程语言,和 HTML 有点像,只不过是专门为写作准备的极简格式。Markdown 的语法很简单,只有一些简单的符号,我们只需学习这几个简单的符号,然后插入到写作内容中,不用关心排版。
程序员大多都不喜欢使用 Word 这类富文本编辑器,因为不可控因素太多,各种形式、用法和风格,而且花样繁多,强依赖于编辑器,换个编辑器用法又不一样了。
众望所归的选择还是 Markdown,排版都是可复制的,文字的排版只是多打几个符号而已,最终产出的只是一个纯文本,非常利于传播和迁移。所以 Markdown 才是程序员的最爱。
目前市面上比较流行的 Markdown 编辑器琳琅满目,本文也无法为大家一一介绍,这里只推荐几个我认为最最最优秀的。
Typora
Typora [1] 最吸引人的特性就是它的即时渲染,也就是所谓的 所见即所得 。一般的 Markdown 编辑器都分为编辑栏和预览栏,Typora 将其合二为一,实时预览,只要你敲入相应的标记符号就立马为你转换为对应的样式,就像写 Word 一样流畅自如。这是本文在 Typora 中的排版样式:
![](http://mdimg.wxwenku.com/getimg/ccdf080c7af7e8a10e9b88444af98393afd85d7f43f494d2a66bc348eccfade5c772e997e67a3f560605ed42a7210a6d.jpg)
遗憾的是 Typora 目前已经开始收费,但这是合理的,之前 Typora 发布的都是测试版,免费供大家使用,现在正式版开始取消免费,毕竟开发也需要付出,我们要尊重开发者,优质的产品值得付费。我们可以选择不用 Typora,但不必对其收费行为冷嘲热讽。
VS Code
VS Code [2] 虽然是一个代码编辑器,但由于它的功能过于强大,插件过于丰富,扩展性极强,所以人们也常常用它来写作。
Visual Studio Code(简称 VS Code)是一个由微软开发,同时支持 Windows 、 Linux 和 macOS 等操作系统且开放源代码的代码编辑器,它支持测试,并内置了 Git 版本控制功能,同时也具有开发环境功能,例如代码补全(类似于 IntelliSense)、代码片段和代码重构等。该编辑器支持用户个性化配置,例如改变主题颜色、键盘快捷方式等各种属性和参数,同时还在编辑器中内置了扩展程序管理的功能。——维基百科
VS Code 借助插件的力量可以实现和 Typora 旗鼓相当的能力。VS Code 默认情况下内置了 Markdown 的预览功能,效果如下:
![](http://mdimg.wxwenku.com/getimg/6b990ce30fa9193e296dd37902816f4bd41f412bd1cb9fa986e6ce3cc6a17e6b21ce8c5d6604692249fe806c651070f2.jpg)
要想实现即时预览的能力,就需要借助一款强大的插件: Office Viewer 。
![](http://mdimg.wxwenku.com/getimg/6b990ce30fa9193e296dd37902816f4b20d70a16c7c831cdb30b80b1f10e6aece67697678867074766f5c914ed45359c.jpg)
这货不但可以实时预览编辑 Markdown,还能显示 PDF 文档和 Excel 表格,简直就是简直了。
装好该插件后,需要在内置文件浏览器里依次 右键 --> 打开方式 ,
![](http://mdimg.wxwenku.com/getimg/ccdf080c7af7e8a10e9b88444af98393241253af70af77f7bc368cff12276f80221be3df87f9b5fcfbe1e7a780a3d994.jpg)
然后在弹出的面板中选择 Office Viewer。
![](http://mdimg.wxwenku.com/getimg/6b990ce30fa9193e296dd37902816f4b112512333abc1061a1604d6a99d8a05d7d93351b2479d8e55c01404d9b7fd201.jpg)
最终效果如下:
![](http://mdimg.wxwenku.com/getimg/356ed03bdc643f9448b3f6485edc229b1e348d58909be033458787a7ea89660de072e40aefcbb6dd143caf3888782972.jpg)
Obsidian
Obsidian [3] 是一个支持双向链接的笔记管理软件,但我们用它来写 Markdown 也是极好的!Obsidian 最新版本也实现了即时预览功能,只需在编辑器设置中将默认的编辑模式改为即时预览即可。
![](http://mdimg.wxwenku.com/getimg/356ed03bdc643f9448b3f6485edc229b607458a4d1570cf6d041f96593c0b65646d02517f3fee68db5f11b97db432fff.jpg)
最终呈现的效果如下:
![](http://mdimg.wxwenku.com/getimg/ccdf080c7af7e8a10e9b88444af98393e86ee15cf28fdcd5613183fcef0882c58c0a82e0188288774f70f1bb651534e5.jpg)
可以看到其实时预览功能目前还有一些小缺陷,比如引用的样式渲染不太理想,不过后续这些问题都会被修复的,现在只是开始。
关于 Obsidian 作为笔记管理软件本身的强大功能,本文不作过多介绍,感兴趣的可以自己研究。
Hackmd
除了个人创作外,有时我们也需要多人协作编辑 Markdown。即使是个人创作,有时也需要请多人帮忙提出改进建议。如果有这方面的需求,可以使用 Hackmd [4] 来协作。在 Hackmd 中,正在编辑这篇文章的人可以同时看见其他协作者正在编辑的位置,编辑一段文字后还可以看见这段文字是谁写的,不同作者用不同颜色表示在这段文字的左边或者下面。还可以对选中的内容通过留言的形式提出改进的建议。
![](http://mdimg.wxwenku.com/getimg/356ed03bdc643f9448b3f6485edc229b028ca08894b39c8e197f5368cadbd4b8debbc90f01290735298114de750bba70.jpg)
写作类型
笔者目前工作的领域是云原生,更宽泛一点则是基础架构领域,这个领域的技术内容创作类型大概可以分为以下几类:
-
问题解决类:该类文章以问题为切入点,整篇文章都是围绕着如何解决这个问题,包括问题的前因后果、问题的解决思路与步骤、避坑方法等。比如这篇: :point_right: 凌晨 12 点突发 Istio 生产事故!一顿操作猛如虎解决了 。
-
安装部署类:这一类文章比较容易理解,就是记录某个开源项目的安装部署过程。例如这篇: :point_right: 使用 KubeKey 快速离线部署 KubeSphere 集群 。
-
最佳实践类:比安装部署类的文章更加深入,涉及到实际业务的落地,需要根据实际业务来规划架构,众多因素都要考虑在内,比如高可用、弹性伸缩、故障检测、保持连接等等。例如这篇: :point_right: 去哪儿网业务大规模容器化最佳实践 。
-
技术分享类:这类文章纯粹就是为了分享自己学习某个技术的心得体会,比如这篇: :point_right: KubeSphere 核心架构浅析 。
-
行业趋使观点类:这类文章主要是发表一些个人观点,比如这篇: :point_right: 云原生的 WebAssembly 能取代 Docker 吗?。
还有一些其他的类型我就不列举了,主要就是上面这几类。
写作流程
确定好写作方向后,就可以构思写作内容了。当然了,首先得确定文章主题才能构思内容,没确定文章主题之前是没法提笔就写的。
构思
一篇好的文章主题需要一个好的 Idea,好的 Idea 需要持续积累。我会根据自己平时关注的资讯、读到的文章来确定近期准备写的原创文章主题,如果我读到比较优秀的英文文章,也会把它纳入到翻译的计划之内。俗话说得好,好记性不如烂笔头,不管是原创还是翻译,这些文章主题都要靠记录才能积累下来,你可以记到纸上,也可以记到笔记软件里。我自己就在使用 Obsidian 记录平时积累的写作主题:
![](http://mdimg.wxwenku.com/getimg/6b990ce30fa9193e296dd37902816f4bd6c7fcbc9da65ba967d7232d74861202a022a145fe1e307a033078f45269ace4.jpg)
大纲
当你决定开始根据某个文章主题动笔写作之前,还有一件重要的事情要做,那就是列出文章的大纲。先列出文章的大纲会让你的写作事半功倍,有了大纲就有了清晰的脉络,层次分明,不会像无头苍蝇一样想到哪写到哪。我一般都是用思维导图的形式来呈现文章的大纲,VS Code 有专门的插件( markmap [5] )可以帮助我们将文章的多级标题转化为思维导图的形式。
![](http://mdimg.wxwenku.com/getimg/356ed03bdc643f9448b3f6485edc229bbb757cda91d716aaba9b5560131f0f1062ac70237d31a6cd32554354c1d62c37.jpg)
或者你也可以直接使用专门的思维导图工具来疏理大纲,比如我使用的是在线版的 processon [6] :
![](http://mdimg.wxwenku.com/getimg/6b990ce30fa9193e296dd37902816f4b3b3559fd35e08678b2373be23b7c4408c5df2f86616a83def7802dbe1c1fd6f6.jpg)
大纲同时也是文章的多级标题,比如我这篇文章的大纲就包含了二级标题和三级标题,一般不建议使用四级标题,除非实在有必要。
文章排版
技术文章的排版有很多需要注意的规范,本文就不一一说明了,感兴趣的可以参考阮一峰的 中文技术文档写作规范 [7] 。
本文只强调几个需要重点注意的事项:
-
Markdown 的标记语法有多种表示形式,比如无序列表既可以使用 '+' 号,也可以使用 '-'、'*' 等符号,大家在写作时尽量统一自己的标记语法,如果你想使用 '+' 号,就全部使用 '+' 号,不然看起来会很混乱。
-
每一个段落之间隔一个 空行 ,尽量避免冗长的段落,如果你的段落内容很长,想办法把它拆分成更多的段落。
-
中英文混排时需要在中英文之间插入一个空格,比如:
错误:KubeSphere集群
正确:KubeSphere 集群为了省去自己手动㪣空格的麻烦,可以借助一些第三方工具来完成。如果你有自己的个人博客,可以使用 『 赫蹏 [8] 』这个库,他是专为中文内容展示设计的排版样式增强,基于通行的中文排版规范而来,可自动为你的中英文之间加空格。如果你想在写作时就解决空格的烦恼,搜狗输入法也可以帮你自动加空格,具体的配置方法自己去搜一下,我电脑上没有搜狗输入法,不方便演示。
辅助工具
真正动笔写作的时候,你会发现有很多地方需要借助第三方工具来辅助自己,比如画架构图、截图等等,如果不选择合适的工具来完成这些操作,你可能会举步维艰。
截图
macOS 从 10.14 开始便自带截图 App,只需要按下 Shift-Command-5(或使用启动台)以打开“截屏”就能显示该工具。
![](http://mdimg.wxwenku.com/getimg/ccdf080c7af7e8a10e9b88444af98393f1a324574ce6a20e54af41405f5fc2fd2ca191eebccf7e34eb777b4fa36afba8.jpg)
功能非常丰富,既可以捕捉整个屏幕,也可以捕捉屏幕的一部分或者之间捕捉特定的窗口,除此之外还可以录制屏幕。
除了自带的截图工具,还有一些第三方的截图工具也很优秀,这里只推荐两个我认为最最最优秀的:
-
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 平台,客户端项目地址: http://github.com/jgraph/drawio-desktop 。
-
Cloudcraft [13] : 如果你更倾向于炫酷的三维架构图,可以选择使用 Cloudcraft,只不过内置的三维图标有点少哦。
图床
无论是截图还是自己画的图,最终都要上传到某个地方然后提供一个外网可以直接访问的链接,这个用来存图片的地方就叫做『 图床 』。
目前网上免费的图床太多了,最知名的应该就是 sm.ms [14] 了,登录用户有 5GB 的免费空间,个人用几年足矣。不过服务器不在国内,访问速度不太行。
除了免费的图床之外,还有一些本身不是图床的平台也可以拿来当图床用,比如 GitHub。。新建个专门的仓库用来存图片,简直不要太香。如果嫌速度慢,可以使用著名的 CDN jsDelivr [15] 来反代,到国内速度贼快,国内线路走的是 CDN 提供商 网宿 [16] 。推荐使用这个 Github 增强油猴脚本 [17] ,可以直接显示 GitHub 文件的各个加速 CDN 的链接。
![](http://mdimg.wxwenku.com/getimg/6b990ce30fa9193e296dd37902816f4bacd22675a29819046612cabd67f42c61b9a890d505ddb83e13b7a032b826e3e3.jpg)
但是很遗憾,去年年底 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 内容粘贴到编辑器中,然后点击『格式化文档』即可。
写在最后
以上就是我关于如何进行技术内容创作的经验之谈,从写作对个人的价值谈到技术内容的创作选型,再到文章的排版和辅助工具,希望能帮助大家开启自己的技术内容创作之路。当然,其中肯定有考虑不周之处,望海涵,也欢迎补充更好的建议。
引用链接
Typora: http://www.typora.io/
VS Code: http://code.visualstudio.com/
Obsidian: http://obsidian.md/
Hackmd: http://hackmd.io/
markmap: http://github.com/gera2ld/markmap-vscode
processon: http://www.processon.com/i/564c654de4b02cebc6408721
中文技术文档写作规范: http://github.com/ruanyf/document-style-guide
赫蹏: http://github.com/sivan/heti
Shottr: http://shottr.cc/
iShot: http://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
Omnigraffle: http://www.omnigroup.com/omnigraffle
diagrams.net: http://app.diagrams.net
Cloudcraft: http://app.cloudcraft.co
sm.ms: http://sm.ms/
jsDelivr: http://www.jsdelivr.com
网宿: http://www.wangsu.com/
Github 增强油猴脚本: http://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
PicGo: http://github.com/Molunerfinn/PicGo/
uPic: http://github.com/gee1k/uPic
HeySpace: http://github.com/louisun/HeySpace
墨滴: http://www.mdnice.com/
KubeSphere (http://kubesphere.io)是在 Kubernetes 之上构建的 开源容器混合云 ,提供全栈的 IT 自动化运维的能力,简化企业的 DevOps 工作流。
KubeSphere 已被 Aqara 智能家居、爱立信、本来生活、东软、华云、新浪、三一重工、华夏银行、四川航空、国药集团、微众银行、杭州数跑科技、紫金保险、去哪儿网、中通、中国人民银行、中国银行、中国人保寿险、中国太平保险、中国移动、中国联通、中国电信、天翼云、中移金科、Radore、ZaloPay 等海内外数千家企业采用。KubeSphere 提供了开发者友好的向导式操作界面和丰富的企业级功能,包括 Kubernetes 多云与多集群管理、DevOps (CI/CD)、应用生命周期管理、边缘计算、微服务治理 (Service Mesh)、多租户管理、可观测性、存储与网络管理、GPU support 等功能,帮助企业快速构建一个强大和功能丰富的容器云平台。
:sparkles: GitHub :http://github.com/kubesphere
:computer: 官网(中国站) :http://kubesphere.com.cn
:man::computer: 微信群: 请搜索添加群助手微信号 kubesphere
:link: 企业服务 : http://kubespher e.cloud
- 云原生爱好者周刊:利用 DNS 计算圆周率
- 使用 KubeKey 搭建 Kubernetes/KubeSphere 环境的"心路(累)历程"
- 云原生爱好者周刊:使用 GitOps 来动态管理 Grafana 的数据源
- KubeSphere 迈入新的里程碑 —— 10000 颗星星!
- 云原生爱好者周刊:STUNner 助你在 K8s 集群中使用 WebRTC 服务
- 云原生爱好者周刊:STUNner 助你在 K8s 集群中使用 WebRTC 服务
- 云原生爱好者周刊:这款支持全平台的 Podman Desktop 值得一试
- 使用 Notification Manager 构建云原生通知系统
- 云原生爱好者周刊:这款支持全平台的 Podman Desktop 值得一试
- OpenFunction 成为 CNCF 沙箱项目,使 Serverless 函数与应用运行更简单
- 云原生爱好者周刊:KubeSphere 3.3.0 Alpha 版发布
- 云原生爱好者周刊:KubeSphere 3.3.0 Alpha 版发布
- 混合多云时代数据保护难在哪?
- 中科金财区块链平台容器化最佳实践
- Client-go 源码分析之 SharedInformer
- 云原生爱好者周刊:寻找 Netlify 开源替代品
- 在 KubeSphere 中监控集群外部 Etcd
- 云原生爱好者周刊:寻找 Netlify 开源替代品
- Fluent Operator:云原生日志管理的一把瑞士军刀
- Fluent Operator:云原生日志管理的一把瑞士军刀