文档代码化

文档代码化，将文档以类代码的领域特定语言的方式编写，并借鉴软件开发的方式（如源码管理、部署）进行管理。它能够借助于特定的工具进行编辑、预览、查看，又或者是经过专属的系统部署到服务器上。面向非技术人员的文档代码化的一种常见架构模式是： 编辑-发布-开发分离』，

最近一个月里，我在开发一个基于 Git + Markdown 的全新文档系统。我定制了一个基于 markdown 的标记语言，以支持起雷达图、条形统计图、思惟导图等图表的文档系统。这个系统将在将来几个月内发布。固然了，视进度而看，也多是月底。

过去的几年里，咱们一直在讨论各类各样的代码化，基础设施代码化、设计代码化、需求代码化……。在个人那一篇《云研发：研发即代码》中，设计了一个彻底代码化的软件开发流程。而今天咱们将讨论另一个有趣的存在：文档。

在《架构金字塔》中，我将文档定义为支撑五层架构模型的一种存在。由于文档在一个系统中是很是重要的存在，咱们用它来指导开发工做，用它来记录问题，用它来写下规范……。总而言之，它很重要，因此咱们从新讨论一下这个话题。

引子 1：架构决策记录：格式化文档

三年前，当我第一次接触到『架构决策记录』的概念时，我被它的理念所吸引：

• 使用轻量级文本格式化语言描述重大决策
• 跟随代码一块儿版本化
• 使用某种特定的文档格式（标题、上下文、决策、状态、后果）

随后，我使用 Node.js + TypeScript 写了一个 ADR 工具。如今，在个人大部分开源荐中，我都会使用它来管理一些技术决策。由于基于这个理论设计的这个文档系统真很是棒，我能够查询到：

• 一个技术决策发生的时间和架构改变，对应的修改人
• 回溯全部的技术决策，从中整理出架构发展过程
• 全部的决策都是记录在版本控制系统中，可恢复
• 易于管理和维护

对于一个长期开发的系统来讲，它真的很是有用。

引子 2：静态站点生成：数据代码化

静态站点生成是一种混合式的 Web 开发方法，它经过部署预先构建的静态文件进行部署，来让开发者在本地构建基于服务器的网站。

当 GitHub Pages 成为了程序员首选的 博客/内容/文档 服务器时，他/她也采用了静态站点生成这一项技术。静态站点生成有各类各样的优势：

• 可靠性、安全性、稳定性、可用性等更好
• 可版本控制
• 易于测试
• 易于实践持续部署。提交便可上线
• 灵活，易于定制

而事实上，静态站点生成所作的最主要的一件事是：将数据库中的数据进行代码化。采用诸如 Wordpress 这样的 CMS 时，咱们是将数据存储在数据库中，以实现对于数据的 CRUD。一篇文章变为数据库二进制文件中的一个片断。

随后，静态站点生成工具作了第二件事情即是将文本内容可视化出来，便于人们阅读。这样一来，咱们便实现了发布-开发分离。

引子 3：定制的标记语言：扩充

将数据代码化时，咱们面临了一个很是大的挑战：易于编写、阅读的标记语言（如 markdown）只设计了内容的形式，缺乏了内容相关的其它信息，诸如于建立时间、做者、修改时间等等。

因而各个静态站点生成器定制了本身的 markdown，添加了一些额外的信息，如 hexo 采用 :year-:month-:day-:title.md 的形式来管理文章的日期和标题等。这样一来讲，就不须要经过读取这个文章的 Git 信息来构建出整个信息。

咱们所熟悉的 GitHub Flavored Markdown 也是如此，经过不明显破坏内容格式的兼容模式来扩展 markdown 数据字段。

除此，咱们能够定制基于 markdown 数据的图表、思惟导图等内容。

引子 4：编辑-发布-开发分离：面向非技术人员

面向非技术人员设计是代码文档化的一大挑战。做为一个程序员，咱们以为 markdown 语法再简单不过了，可是对于非技术人员来讲并不是如此。他/她须要：一个易于上手的可视化编程器。而要实现这样一个目的，咱们须要在架构上作一些转变，咱们能够尝试使用 『编辑-发布-开发分离』 模式来解决这个问题。

即，咱们将过程拆为了三步：

• 编辑人员，可使用经常使用的编辑器或者是定制的编辑器
• 开发人员，编写内容的展现
• 发布的时候，集成这两部分代码

咱们依旧能够选择用源码管理的方式来管理内容。只须要将数据库接口，转变为 Git 服务器接口便可 —— 固然它们是稍有不一样的。不过呢，把本地的 Git 转换为 Git remote 那就基本一致了。

如此一来，最后咱们的成本就落在改造出一个基于 Git 的 markdown 编辑器。

文档代码化

完美，我又一次在引子里，把中心思想表达完了。

为何你须要将文档代码化？

主要缘由有：文档不代码化，就没有重构的可能性。

剩下的缘由有：

• 二进制的文档难以进行版本管理。想象一下 2020-02-30.docx 和 2020-02-31.docx。
• 没法准确地知道谁是文档的修改者，你们可能都是 admin，又或者是会议上的张三
• 找不到哪一个是最新的文档
• 文档写得很烂，可是你没办法重构二进制文档
• 供应商绑定
• ……

应该还有更多。

什么是文档代码化？

回到正题上：

文档代码化，将文档以类代码的领域特定语言的方式编写，并借鉴软件开发的方式（如源码管理、部署）进行管理。它能够借助于特定的工具进行编辑、预览、查看，又或者是经过专属的系统部署到服务器上。

它具有这么一些特征：

• 使用标记语言编写内容。如 markdown
• 可经过版本控制系统进行版本控制。如 git
• 与编程一致的编程体验（除了内容写不了测试）

而一个高效的文档代码化系统，还具有这么一些特征：

• 持续部署，即修改完内容可自动发布。
• 与特定的形式组织内容索引。如以知识库的形式来组织内容。
• 特定的文本格式。如架构决策记录、静态内容生成，以用于以提供更好的用户体验
• 可支持 REST API。以经过编辑器来修改内容
• 能够支持多种方式的输出。如网站标准 HTML，又或者是 Docx、Latex 等
• 支持编辑、校对工做流
• 支持搜索
• 多人协做

而事实上，大部分的团队并不须要上述的高级功能，并且它们都已经有了成熟的方案。

如何设计一个文档代码化系统？

事实上，咱们在四个引子中标明了咱们所须要的要素：

1. 使用格式化的文档
2. 借助静态站点生成技术来发布系统
3. 经过定制标记语言扩充能力
4. 面向非技术人员实现编辑器

设计一个标记语言及其扩展语法，而后实现它便可。

1. 确立关键因素

考虑到我和个人同事们最近实现了这么一个系统，我仍是忍受一下手的痛楚，简单说一下怎么作这样一个系统。咱们所考虑的主要因素是：

• 图表渲染
• 流程图渲染
• 可视化展现

由于由 DSL 转换成的图表易于修改，而且能够索引。因而乎，咱们：

1. 经过 markdown 的 Code 语法来扩充这些能力
2. 使用 markdown 的 table 和 list 来提供数据
3. 使用 D3.js 来支持流程图绘制
4. 使用 Echarts 来进行图表绘制
5. 尽可能使用 SVG 图片
6. ……

2. 实现一个 MVP

咱们使用 Angular + GitHub，快速实现了一个 MVP：

1. 咱们使用 Git 做为数据库.它就能够实现多人协做的目的，而且能够追踪全部的变化
2. 咱们使用 GitHub Pages 做为服务器。只要一修改文档或者代码，就会部署最新的文档。
3. 咱们使用 marked.js，它可让咱们快速扩展语法。
4. 使用 textarea 结合 markdown 制做了一个简易的编辑器。

随后，咱们在这个基础上进行了快速的迭代。

3. 扩展语法

咱们使用了 markdown 的 code 做为图表的 DSL，扩展了这么一些语法：

• echarts。直接渲染 Echarts 图表
• mindmap。Markdown List 转为思惟导图
• radar。Markdown List 转为雷达图
• process-table。带流程的图表
• process-step。另一种带流程的图表
• pyramid。金字塔图形
• quadrant。四象限图
• class。直接调用 CSS 的 class
• graphviz。使用 Dot 渲染图片
• mermaid。使用 mermaid 可视化
• webcomponents。调用 WebComponents 组件

• toolset。调用 Toolset 相关的组件

  • slider。权衡滑块
  • line-chart。表图

因此，对于使用者来讲，只须要编写下面的代码：

• 质量成熟度评估模型

  • 质量内建: 3 -> 4
  • 优化业务价值: 2 -> 2
  • 质量统一，可视化: 1 -> 5
  • 全员参与: 3 -> 4
  • 快速交付: 4 -> 5
  • 测试做为资产: 2 -> 3
  • 快速反馈: 5 -> 5

config: {"legend": ["当前", "将来"]}

就能够生成对应的图表：

又或者是用于制做技术雷达图：

咱们还经过 config 来输入 JSON，进行必定的懒惰化处理（不要累死本身）。

3.1 重写 markdown 渲染器

咱们在这个过程当中，遇到的最大的挑战是，随着咱们对 markdown 语法的不断扩充，相关的代码已经变成了一坨大泥球。因此，咱们不得不重写了这部分代码：

1. 借助于 marked.js 的 lexer 解析出 token
2. 根据 token 修改生成新的 token
3. 遍历新生成的 token，渲染出元素
4. 结合虚拟滚动，解决性能问题

已经开源在 GitHub，并发布对应的 npm 包：@ledge-framework/render。

4. 发布这个项目

咱们已经在 GitHub 上发布了这个文档化系统，你能够参与到其中的使用和开发。

GitHub：https://github.com/phodal/ledge

项目首页：https://devops.phodal.com/

总结

而后，你就成为了一个 Markdown 工程师，D3.js 设计师，Echart 配置管理员。