文档的编码化是指将文档以类似代码的领域特定语言的形式进行编译，并参考软件开发方法（如源代码管理和部署）进行管理。 可以使用特定工具进行编辑、预览和查看，也可以通过专用系统部署到服务器上。 非技术人员文档编码的常见架构模式是：“编辑-发布-开发分离”。

这一个月以来，我一直在开发一个基于Git+Markdown的新文档系统。 我定制了一个基于markdown的标记语言，支持雷达图、条形图、思维导图等图表的文档系统。 该系统将在未来几个月内发布。 事实上，根据进展情况，可能要到年底了。

这几年我们还在讨论各种规范，基础设施规范，设计规范，需求规范……。 在我的文章《云开发：开发就是代码》中，我设计了一个完全编码的软件开发流程。 明天我们将讨论另一个有趣的存在：文档。

在《架构金字塔》中，我将文档定义为支持五层架构模型的存在。 因为文档在一个系统中非常重要，我们用它来指导开发工作，用它来记录问题，用它来写规范……。 总而言之，这很重要，所以让我们重新讨论一下这个话题。

简介 1：架构决策记录：低格式文档

五年前，当我第一次遇到“建筑决策记录”这个概念时，我就被它的概念所吸引：

之后我使用Node.js+Typescript编写了一个ADR工具。 今天，在我的大多数开源建议中，我使用它来管理一些技术决策。 由于基于这个理论设计的文档系统确实很棒，我可以查询：

对于一个已经开发多年的系统来说，它确实很有用。

简介2：静态站点生成：数据编码

静态站点生成是一种混合 Web 开发方法，允许开发人员通过部署预构建的静态文件进行部署，在本地构建基于服务器的网站。

当 GitHubPages 成为程序员首选的博客/内容/文档服务器时，他/她也采用了静态站点生成技术。 静态站点生成具有多种优点：

事实上，静态站点生成所做的最重要的事情之一是：对数据库中的数据进行编码。 当使用Wordpress等CMS时，我们将数据存储在数据库中，以对数据实现CRUD。 一篇文章成为数据库的补码文件中的一个段。

之后软件开发的文档，静态站点生成工具所做的第二件事是将文本内容可视化，以便人们可以阅读。 这样我们就实现了发布与开发的分离。

入门 3：自定义标记语言：扩展

在对数据进行编码时，我们面临着一个特别大的挑战：易于编写和阅读的标记语言（例如markdown）只设计了内容，而缺乏与内容相关的其他信息，例如创建时间、作者、修改时间等

所以各个静态站点生成器都定制了自己的markdown，并添加了一些额外的信息，比如hexo采用:year-:month-:day-:title.md的方法来管理文章的日期和标题等。 ，不需要阅读本文的Git信息来创建整个信息。

我们熟悉的 GitHub FlavoredMarkdown 也是如此，它通过不显着破坏内容格式的兼容模式来扩展 Markdown 数据数组。

此外，我们还可以根据Markdown数据定制图表和思维导图。

入门指南 4：编辑-发布-开发分离：针对非技术人员

为非技术人员进行设计是记录代码的一大挑战。 作为一名程序员，我们认为 Markdown 语法再简单不过了，对于非技术人员来说则不然。 他/她需要什么：一个易于使用的可视化程序员。 要达到这样的目标，我们需要在结构上做一些改变，我们可以尝试用“编辑-发布-开发分离”的模式来解决这个问题。

也就是说，我们将这个过程分为三个步骤：

我们仍然可以选择通过源代码控制来管理内容。 你只需要把数据库套接字转换成Git服务器套接字——当然它们略有不同。 不过，将本地Git转换为Gitremote基本是一样的。

这样，最终我们的成本就落在了改造一个基于Git的markdown编辑器上。

文件编码

完美软件开发的文档，我又把引言的中心思想表达完了。

为什么需要对文档进行编码？

主要原因是：如果文档不编码，就没有构建的可能。

剩下的原因是：