作为一名成熟的云原生布道师,我是这么写作的
技术写作的价值
写作并不是一件轻松的事情,特别是技术内容创作,它不仅需要兴趣来驱动,而且需要耐心,所以写作这个活动注定不适合所有人。我想无论是写作、演讲,还是录制视频,除了利益驱动无可厚非之外,大家肯定都有一个额外的共同目的:分享。
至于分享之后为了得到什么,那都不重要,比如我就是为了满足自己的虚荣心,说白了就是装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 中,正在编辑这篇文章的人可以同时看见其他协作者正在编辑的位置,编辑一段文字后还可以看见这段文字是谁写的,不同作者用不同颜色表示在这段文字的左边或者下面。还可以对选中的内容通过留言的形式提出改进的建议。
写作类型
笔者目前工作的领域是云原生,更宽泛一点则是基础架构领域,这个领域的技术内容创作类型大概可以分为以下几类:
问题解决类:该类文章以问题为切入点,整篇文章都是围绕着如何解决这个问题,包括问题的前因后果、问题的解决思路与步骤、避坑方法等。比如这篇:凌晨 12 点突发 Istio 生产事故!一顿操作猛如虎解决了。 安装部署类:这一类文章比较容易理解,就是记录某个开源项目的安装部署过程。例如这篇:使用 KubeKey 快速离线部署 KubeSphere 集群。 最佳实践类:比安装部署类的文章更加深入,涉及到实际业务的落地,需要根据实际业务来规划架构,众多因素都要考虑在内,比如高可用、弹性伸缩、故障检测、保持连接等等。例如这篇:去哪儿网业务大规模容器化最佳实践。 技术分享类:这类文章纯粹就是为了分享自己学习某个技术的心得体会,比如这篇:KubeSphere 核心架构浅析。 行业趋使观点类:这类文章主要是发表一些个人观点,比如这篇:云原生的 WebAssembly 能取代 Docker 吗?。
还有一些其他的类型我就不列举了,主要就是上面这几类。
写作流程
确定好写作方向后,就可以构思写作内容了。当然了,首先得确定文章主题才能构思内容,没确定文章主题之前是没法提笔就写的。
构思
一篇好的文章主题需要一个好的 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] : 这是一款非常专业的画图软件,可以画出非常精美的架构图,如果你对架构图的审美要求比较高,推荐使用这个工具。这是我画的关于以 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 内容粘贴到编辑器中,然后点击『格式化文档』即可。
写在最后
以上就是我关于如何进行技术内容创作的经验之谈,从写作对个人的价值谈到技术内容的创作选型,再到文章的排版和辅助工具,希望能帮助大家开启自己的技术内容创作之路。当然,其中肯定有考虑不周之处,望海涵,也欢迎补充更好的建议。
引用链接
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://tinyurl.com/5cwfxdhu,版权归原作者所有。