文档代码化,将文档以类代码的领域特定语言的方式编写,并借鉴软件开发的方式(如源码管理、部署)进行管理。它可以借助于特定的工具进行编辑、预览、查看,又或者是通过专属的系统部署到服务器上。面向非技术人员的文档代码化的一种常见架构模式是:编辑-发布-开发分离』,
最近一个月里,我在开发一个基于 Git + Markdown 的全新文档系统。我定制了一个基于 markdown 的标记语言,以支持起雷达图、条形统计图、思维导图等图表的文档系统。这个系统将在未来几个月内发布。当然了,视进度而看,也可能是月底。
过去的几年里,我们一直在讨论各种各样的代码化,基础设施代码化、设计代码化、需求代码化……。在我的那一篇《云研发:研发即代码》中,设计了一个完全代码化的软件开发流程。而今天我们将讨论另外一个有趣的存在:文档。
在《架构金字塔》中,我将文档定义为支撑五层架构模型的一种存在。因为文档在一个系统中是非常重要的存在,我们用它来指导开发工作,用它来记录问题,用它来写下规范……。总而言之,它很重要,所以我们重新讨论一下这个话题。
三年前,当我第一次接触到『架构决策记录』的概念时,我被它的理念所吸引:
随后,我使用 Node.js + TypeScript 写了一个 ADR 工具。现在,在我的大部分开源荐中,我都会使用它来管理一些技术决策。因为基于这个理论设计的这个文档系统真非常棒,我可以查询到:
对于一个长期开发的系统来说,它真的非常有用。
静态站点生成是一种混合式的 Web 开发方法,它通过部署预先构建的静态文件进行部署,来让开发者在本地构建基于服务器的网站。
当 GitHub Pages 成为了程序员首选的 博客/内容/文档 服务器时,他/她也采用了静态站点生成这一项技术。静态站点生成有各种各样的优点:
而事实上,静态站点生成所做的最主要的一件事是:将数据库中的数据进行代码化。采用诸如 Wordpress 这样的 CMS 时,我们是将数据存储在数据库中,以实现对于数据的 CRUD。一篇文章变为数据库二进制文件中的一个片段。
随后,静态站点生成工具做了第二件事情便是将文本内容可视化出来,便于人们阅读。这样一来,我们便实现了发布-开发分离。
将数据代码化时,我们面临了一个非常大的挑战:易于编写、阅读的标记语言(如 markdown)只设计了内容的形式,缺少了内容相关的其它信息,诸如于创建时间、作者、修改时间等等。
于是各个静态站点生成器定制了自己的 markdown,添加了一些额外的信息,如 hexo 采用 :year-:month-:day-:title.md
的形式来管理文章的日期和标题等。这样一来说,就不需要通过读取这个文章的 Git 信息来构建出整个信息。
我们所熟悉的 GitHub Flavored Markdown 也是如此,通过不明显破坏内容格式的兼容模式来扩展 markdown 数据字段。
除此,我们可以定制基于 markdown 数据的图表、思维导图等内容。
面向非技术人员设计是代码文档化的一大挑战。作为一个程序员,我们觉得 markdown 语法再简单不过了,但是对于非技术人员来说并非如此。他/她需要:一个易于上手的可视化编程器。而要实现这样一个目的,我们需要在架构上做一些转变,我们可以尝试使用 『编辑-发布-开发分离』 模式来解决这个问题。
即,我们将过程拆为了三步:
我们依旧可以选择用源码管理的方式来管理内容。只需要将数据库接口,转变为 Git 服务器接口即可 —— 当然它们是稍有不同的。不过呢,把本地的 Git 转换为 Git remote 那就基本一致了。
如此一来,最后我们的成本就落在改造出一个基于 Git 的 markdown 编辑器。
完美,我又一次在引子里,把中心思想表达完了。
主要原因有:文档不代码化,就没有重构的可能性。
剩下的原因有:
2020-02-30.docx
和 2020-02-31.docx
。应该还有更多。
回到正题上:
文档代码化,将文档以类代码的领域特定语言的方式编写,并借鉴软件开发的方式(如源码管理、部署)进行管理。它可以借助于特定的工具进行编辑、预览、查看,又或者是通过专属的系统部署到服务器上。
它具备这么一些特征:
而一个高效的文档代码化系统,还具备这么一些特征:
而事实上,大部分的团队并不需要上述的高级功能,而且它们都已经有了成熟的方案。
事实上,我们在四个引子中标明了我们所需要的要素:
设计一个标记语言及其扩展语法,然后实现它即可。
考虑到我和我的同事们最近实现了这么一个系统,我还是忍受一下手的痛楚,简单说一下怎么做这样一个系统。我们所考虑的主要因素是:
因为由 DSL 转换成的图表易于修改,并且可以索引。于是乎,我们:
我们使用 Angular + GitHub,快速实现了一个 MVP:
随后,我们在这个基础上进行了快速的迭代。
我们使用了 markdown 的 code
作为图表的 DSL,扩展了这么一些语法:
所以,对于使用者来说,只需要编写下面的代码:
```radar
- 质量成熟度评估模型
- 质量内建: 3 -> 4
- 优化业务价值: 2 -> 2
- 质量统一,可视化: 1 -> 5
- 全员参与: 3 -> 4
- 快速交付: 4 -> 5
- 测试作为资产: 2 -> 3
- 快速反馈: 5 -> 5
config: {"legend": ["当前", "未来"]}
```
就可以生成对应的图表:
我们还通过 config 来输入 JSON,进行一定的懒惰化处理(不要累死自己)。
我们在这个过程中,遇到的最大的挑战是,随着我们对 markdown 语法的不断扩充,相关的代码已经变成了一坨大泥球。所以,我们不得不重写了这部分代码:
已经开源在 GitHub,并发布对应的 npm 包:@ledge-framework/render
。
我们已经在 GitHub 上发布了这个文档化系统,你可以参与到其中的使用和开发。
GitHub:https://github.com/phodal/ledge
项目首页:https://devops.phodal.com/
然后,你就成为了一个 Markdown 工程师,D3.js 设计师,Echart 配置管理员。
围观我的Github Idea墙, 也许,你会遇到心仪的项目