博客开发文档,博客开发的意义

出品 | 开源中国

文 | 大东BE

无论是写 API 文档还是输出技术博客博客开发文档，技术写作已经成为各位程序员写代码之余最多的工作，趁手的文档编辑器或许是仅次于 IDE 的吃饭家伙事儿。

其实最早的计算机技术文档可以追溯到 1944 年，美国哈佛大学 Mark 1 ASCC 自动序列控制计算机研发小组成员 Grace Hopper 为他们研发的这台早期计算机撰写博客开发文档了操作手册。

还有另一个说法称“世界上第一本电子计算机手册”是 BIAC 二进制自动计算机的操作和维护手册，由 Joseph Chapline 于 1949 年编写。该手册创建了一系列计算机手册标准，并成为后来诞生的许多其他计算机手册的模板。

尽管这两个案例可以追溯到 1940 年代，但直到 1960 年代后期，随着面向过程的编程语言在第三代微型集成电路计算机中的使用，才使得代码注释和技术文档成为软件开发的标配。

也是从这一时期开始，为了统一文本在不同计算机软硬件上的格式标准，GML、TEX、LaTex、HTML、Markdown 等标记语言相继面世，这些标记语言将计算机中的文本以及文本相关的其他信息结合起来，展现出关于文档结构和数据处理细节的计算机文字编码，为计算机文本的格式制定了标准。这些标记语言也成为不同时期软件工程师们撰写开发文档时必备的技能。

其中，Markdown 作为最年轻的标记语言到被广泛沿用至今，成为很多习惯纯键盘操作的开发者们用于技术写作的不二之选。

为什么开发者喜欢 Markdown？

今天流行的大部分开发者工具都支持 Markdown，包括 GitHub、Gitee、Trello、Slack 等。大部分开发者也会采用支持 Markdown 编辑器的开源工具来搭建自己的个人博客。

然而在博客场景仍处于起步阶段的 2000 年代初期，WordPress 和 TypePad 等建站平台在编辑器功能上并没有提供太多的便利，这时候的开发者写文档仍需使用 HTML 来处理文本格式，技术博主和 UI 设计师 John Gruber 便是其中的一员。虽然 Gruber 喜欢在线写作和分享自己的技术内容，但他实在受够了使用 HTML 格式化所有内容的麻烦。

▲ John Gruber

受到纯文本电子邮件通信美学的启发，在 Reddit 联合创始人 Aaron Swartz 的协助下，John Gruber 于 2004 年 3 月 19 日推出了第一个版本的 Markdown。

Markdown 相比 HTML 等富文本格式更加轻便，只包含分级标题、字体加粗、斜体、引用、添加代码块、插入图片/超链等程序员群体常用的文档功能，且格式非常简单，可以实现排版+写作同时进行，且无需使用鼠标点选调整格式，非常适合习惯了纯键盘操作的程序员们。

另一方面，Markdown 简洁的语法非常容易被浏览器解析，这使得 Markdown 几乎适用于任何 Web 场景，这也是其日后被广泛用于代码托管平台 Readme、开源项目在线文档、开发者个人博客等场景的重要原因之一。

得益于这些专为技术文档而生的优秀特性，Markdown 很快在开发者群体中流行开来。

始于 Markdown 的语雀

目前，除了自建博客外，各类支持 Markdown 的写作平台已经成为了国内开发者首选的文档和知识库建立工具，例如 Notion、语雀、石墨文档、印象笔记等。

其中，语雀作为蚂蚁集团内部孵化的项目，在开发者社区中收获了不俗的口碑。据统计，在语雀最受欢迎的文档插入功能卡片中，使用量排行第一的是图片卡片，现在已经有 7100 万个，而使用量排行第二的就是代码块，达到 2500 万个，可见开发者群体在语雀用户中的占比之大。

来自语雀的研发工程师阎王告诉我们，语雀最初也是一名蚂蚁的程序员利用业余时间开发的 Markdown 编辑器。

2016 年，蚂蚁金融云需要一个工具来承载它的文档，负责这项工作的工程师利用业余时间，搭建了这个文档工具，也就是语雀的雏形。项目的初期，没有任何人员和资源支持，同时也是为了快速验证原型，技术选型上选择了最低成本的方案。其中，应用层客户端选用了 React 技术栈，结合蚂蚁开源的 Ant Design，并采用 CodeMirror 实现了一个功能强大、体验优雅的 markdown 在线编辑器。

2017 年，随着语雀得到团队内部的认可，项目的目标已经不仅仅是金融云研发团队的文档工具，而是成为阿里所有员工的知识管理平台。于是，语雀在面向技术人员 Markdown 编辑器之外，还向非技术创作者提供了富文本编辑器，并选择了更“Web”的路线，在富文本编辑器中加入了公式、文本绘图、思维导图等功能。

这一时期，语雀的前端编辑器从 codeMirror 迁移到 Slate。为了更好的实现语雀编辑器的功能，项目团队内部 fork 了 Slate 进行深入开发，同时也自定义了一个独立的内容存储格式，以提供更高效的数据处理和更好的兼容性。

随着编辑器越来越复杂，在 slate 的基础上进行开发遇到的问题越来越多，语雀团队最终还是走上了自研编辑器的道路，并基于浏览器的 Contenteditable 实现了富文本编辑器，通过 Canvas 实现了表格编辑器，通过 SVG 实现了思维导图编辑器。

自 2018 年正式对外提供服务以来，语雀团队就采用编辑器自研，底层的服务全面上云的形式，通过 JavaScript 全栈进行研发，以云服务的方式为企业级用户和个人知识工作者者提供知识创作和管理工具。

开发者喜欢的编辑器因素

阎王 —— 这位花名霸气的技术小哥在写作方面的经历与开源中国的很多技术博主类似，除了是语雀研发团队的一名开发者外，业余时间也是一个技术自媒体，用“小胡子哥”这个笔名写了十多年的技术博客。

“小胡子哥”最初在博客园上做内容分享，后来又购买云服务器自建博客，也曾将博客整体迁移到 GitHub 上，兜兜转转在 2016 年首次接触到了语雀，成为了语雀的早期用户。

阎王介绍，自己日常的写作会有三种状态博客开发文档：

思考，一种是把脑子里面灵光乍现的内容记录下来，这个时候对工具几乎是没有任何要求的，只要能输入即可；整理，第二种状态是整理思绪，其实写一篇文章最复杂的工序就在这个环节，我们需要把脑海中的内容和已有的内容做整合，让零碎的知识产生结构和关联，在这个过程中，经常会用到一些绘图工具、数据统计和分析工具；表达，将整理好的内容撰写成文，在敲击键盘的时候，会不断地思考，假设我此时是一名读者，我正在看这些文字，我的感受是怎样的，不断地尝试换位思考，这样才有可能写出一篇别人愿意看的文章。

对于大部分技术写作者来说，需要的正是能满足第二种状态的编辑工具。以语雀为例，阎王认为语雀之所以能够吸引开发者群体，得益于其产品设计在洞悉技术写作的需求方面做得很好。

首先是语雀的代码块功能。早期的语雀只是简单的 Markdown 代码块渲染。经过迭代，语雀代码块在样式和支持的语言上都进行了加强，支持近百种常见的编程语言样式；此外还增加了代码块的命名、主题切换、高度调整、函数折叠等功能，能够满足绝大多数代码展示的需要。

语雀的画板功能也非常好用，不仅支持文本绘图，还结合了思维导图和流程图，提供非常丰富的绘图元素，提供了快速 *** 技术架构图的能力。

利用语雀的开放接口，开发者可以把语雀上的博客同步推送到 GitHub 的个人仓库：

除此之外，语雀还有能全键盘操作的文档编辑器、知识库目录、创作指数绿墙等等，这些都是对开发者群体来说非常友好的元素。

最后值得一提的是，阎王还透露团队计划将语雀文档编辑器的代码开源，期望在社区的开放合作模式下，让语雀编辑器变得更好更强。

写作对于每一个开发者来说都是非常好的习惯，能够帮助我们实现终身学习的目标，而一款好用的文档工具能够帮助我们将所学所想建立成知识库，并受益终生。

“在程序员的日常里，不仅我们的代码高并发地跑在机器上，脑子也是一样的，每天我们都要处理非常非常多的事务，处理不过来怎么办呢？这个时候就需要有一个信息的中转站，控制一下信息流转的速度，同时呢，在这个中转站里面，把无效信息给剔除掉，然后分门别类地做好归类，最后再交给大脑处理，这样才能游刃有余地把事情一件一件做好。这个理念在语雀里也有很好的体现。”