发布信息

干货笔记整理:技术写作与记录的重要性及发展历程

作者:软荐小编      2024-08-21 15:06:13     124

文档模板开发软件技术方案_软件开发技术文档模板_文档开发工程师做什么

往期干货笔记汇总

大家好,今天我们来聊聊知识记录的话题。

记录和回顾对于开发者来说其实是很重要的,做笔记也可以帮助我们梳理自己的知识和技术体系。

无论是编写 API 文档,还是做笔记、输出技术博客,技术写作与记录可以说是程序员除了写代码之外最常做的事情之一,一个好用的文档编辑器可能是继 IDE 之后第二重要的工具。

其实,最早的计算机技术文献可以追溯到1944年,当时美国哈佛大学Mark 1 ASCC自动序列控制计算机研发团队成员Grace Hopper为他们研制的早期计算机撰写了一份操作手册。

另一种说法是,“世界上第一本电子计算机手册”是约瑟夫·查普林(Joseph Chapline)于1949年编写的《BIAC二进制自动计算机操作与维护手册》,这本手册开创了一系列计算机手册标准,后来成为……虽然这两个例子都可以追溯到20世纪40年代,但代码注释和技术文档直到20世纪60年代末,随着第三代微集成电路计算机中面向过程的编程语言的使用,才开始流行起来,成为软件开发的标准。

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

文档开发工程师做什么_软件开发技术文档模板_文档模板开发软件技术方案

其中Markdown作为最年轻的标记语言,至今依然被广泛使用,成为了很多习惯纯键盘操作进行技术写作的开发者的首选。

为什么开发人员喜欢 Markdown

目前流行的开发者工具大多都支持Markdown,包括GitHub、Gitee、Trello、Slack等,大多数开发者也使用支持Markdown编辑器的开源工具来构建自己的个人博客。

然而,在 2000 年代初期,博客行业还处于起步阶段,WordPress 和 TypePad 等网站构建平台在编辑功能方面并没有提供太多便利。当时,开发人员在撰写文档时仍必须使用 HTML 来处理文本格式。校长兼 UI 设计师 John Gruber 就是其中之一。尽管 Gruber 喜欢撰写和在线分享他的技术内容,但他厌倦了用 HTML 格式化所有内容的麻烦。

文档模板开发软件技术方案_软件开发技术文档模板_文档开发工程师做什么

约翰·格鲁伯

受到纯文本电子邮件通信美学的启发,John Gruber 于 2004 年 3 月 19 日推出了 Markdown 的第一个版本。

Markdown 相较于 HTML 等富文本格式而言更为轻量,仅包含了程序员常用的文档功能,例如分层标题、加粗字体、斜体、引用、添加代码块、插入图片/超链接等,并且格式非常简单软件开发技术文档模板,可以实现排版+书写同时进行,无需使用鼠标点击、调整格式,非常适合习惯纯键盘操作的程序员。

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

得益于这些专为技术文档设计的优秀功能,Markdown 很快就在开发者社区中流行起来。

语雀源于 Markdown

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

之前分享过很多写作工具、笔记平台相关的问题,每次都有不少朋友在评论里推荐语雀。

作为蚂蚁内部孵化的项目,语雀经常被开发者提及。语雀的研发工程师曾表示,语雀最初是一个蚂蚁程序员在业余时间开发的Markdown编辑器。

2016 年,蚂蚁金服云需要一个工具来托管其文档,负责这项工作的工程师利用业余时间打造了这个文档工具,也就是语雀的原型。项目前期没有任何人员和资源的支持,为了快速验证原型,在技术选型上选择了成本最低的方案,应用层客户端选择了 React 技术栈,结合蚂蚁金服开源项目 Ant Design,使用 CodeMirror 实现了一个强大而优雅的 Markdown 在线编辑器。

2017年,随着语雀在团队内部获得认可,项目的目标不再仅仅是金融云研发团队的文档工具,而是成为全阿里人的知识管理平台。此外,它还为非技术创作者提供了富文本编辑器,并选择了更加“Web化”的路线,在富文本编辑器中添加了公式、文字绘制、思维导图等功能。

在此期间,语雀的前端编辑器从codeMirror迁移至Slate,为了更好地实现语雀编辑器的功能,项目组fork了Slate进行深度开发,同时还定制了独立的内容存储格式,以提供更高效的数据处理和更好的兼容性。

随着编辑器越来越复杂,基于 Slate 的开发遇到的问题也越来越多,语雀团队最终走上了自研编辑器的道路,基于浏览器的 ContentEditable Editor 实现了富文本,通过 Canvas 实现了表格编辑器,通过 SVG 实现了思维导图编辑器。

自2018年正式上线服务以来,语雀团队采用自研编辑器、完全云化底层服务的形式,通过Javascript全栈进行研发,向企业用户和个人知识工作者提供云端服务的知识创造和管理工具。

开发人员喜欢该编辑器的因素

语雀的一位研发工程师曾说,自己每天的写作过程有三种状态:

对于大部分技术写作者来说,他们需要的是一款能够满足第二种境界的编辑工具,语雀之所以能够吸引开发者,是因为它的产品设计很好地理解了技术写作的需求。

首先是代码块功能。语雀早期只是单纯的 Markdown 代码块渲染软件开发技术文档模板,历经迭代,其代码块在样式、支持语言等方面均有增强,支持近百种常见编程语言样式,此外还具备代码块命名、主题切换、高度调整、函数折叠等功能,可以满足绝大部分代码展示需求。

文档模板开发软件技术方案_文档开发工程师做什么_软件开发技术文档模板

另外它的画板功能也非常好用,不仅支持文本绘制,还结合了思维导图和流程图,提供了非常丰富的绘图元素和快速创建技术架构图的能力。

此外,利用其开放接口,开发者还可以将语雀上的博客推送到GitHub上的个人仓库中,这在一般情况下是可以实现的。

软件开发技术文档模板_文档开发工程师做什么_文档模板开发软件技术方案

最后值得一提的是,语雀研发工程师还透露,团队计划将语雀文档编辑器的代码开源,希望在社区的开放合作模式下,将语雀编辑器做得更好、更强。

“程序员的日常生活中,不仅我们的代码在高并发的机器上运行,我们的大脑同样如此,每天要处理很多事务,处理不了怎么办?这时候就需要一个信息中转站,控制信息流动的速度。同时在这个中转站,无效信息被淘汰,然后分类成不同的类别,最后交给大脑处理,这样就能轻轻松松把事情做好一件事情。”

总之,写作和记录对于开发者来说很重要,也能帮助我们梳理自己的知识和技术体系。坚持下去,好处多多。

相关内容 查看全部