文档代码化重塑软件开发

1.8. 文档代码化重塑软件开发#

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

最近一个月里，我在开发一个基于 Git + Markdown 的全新文档系统。 我定制了一个基于 markdown 的标记语言，以支持起雷达图、条形统计图、思维导图等图表的文档系统。 这个系统将在未来几个月内发布。当然了，视进度而看，也可能是月底。 过去的几年里，我们一直在讨论各种各样的代码化，基础设施代码化、设计代码化、需求代码化……。 在我的那一篇《云研发：研发即代码》中，设计了一个完全代码化的软件开发流程。 而今天我们将讨论另外一个有趣的存在：文档。在《架构金字塔》中，我将文档定义为支撑五层架构模型的一种存在。 因为文档在一个系统中是非常重要的存在，我们用它来指导开发工作，用它来记录问题，用它来写下规范……。 总而言之，它很重要，所以我们重新讨论一下这个话题。

为什么你需要将文档代码化？

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

剩下的原因有：

  • 二进制的文档难以进行版本管理。想象一下 2020-02-30.docx 和 2020-02-31.docx。

  • 无法准确地知道谁是文档的修改者，大家可能都是 admin，又或者是会议上的张三

  • 找不到哪个是最新的文档

  • 文档写得很烂，但是你没办法重构二进制文档

  • 供应商绑定

  • ……

应该还有更多。

什么是文档代码化？

回到正题上：

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

它具备这么一些特征：

  • 使用标记语言编写内容。如 markdown

  • 可通过版本控制系统进行版本控制。如 git

  • 与编程一致的编程体验（除了内容写不了测试）

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

  • 持续部署，即修改完内容可自动发布。

  • 与特定的形式组织内容索引。如以知识库的形式来组织内容。

  • 特定的文本格式。如架构决策记录、静态内容生成，以用于以提供更好的用户体验

  • 可支持 REST API。以通过编辑器来修改内容

  • 可以支持多种方式的输出。如网站标准 HTML，又或者是 Docx、Latex 等

  • 支持编辑、校对工作流

  • 支持搜索

  • 多人协作

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

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

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

  • 使用格式化的文档

  • 借助静态站点生成技术来发布系统

  • 通过定制标记语言扩充能力

  • 面向非技术人员实现编辑器

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