MBT（A model based document builder）文档模型化生成工具用户手册——30倍效率文档撰写工程化方法

1 简介

在软件工程领域，工程文档通常主要包括实施方案、需求分析、软件设计、测试报告、验收大纲、用户手册等几种。这些文档中，通常要求内容丰富，能够体现整个软件工程大部分信息；易于理解，需要制作各种表格，绘制各种图形，包括UML图。可见，文档撰写的工作量巨大，需要有工具支撑，以提高工作效率。

“文档模型化生成工具”的研制目的是为了简化工程文档，减少文档撰写的工作量，所针对的实际现象是：

（1）产品研发人员之间文档样式、模板不统一，格式过于复杂，编辑、合并、分块工作会耗费大量时间。

（2）同一项目中，文档之间联系紧密，其中往往包括一些重复信息。

（3）章节之间，隐含了组成、从属关系信息。

（4）表格制作、图形绘制工作工作量大。

（5）段落、插图、表格、目录、编号、页码、样式等文档要素要进行正确美观的格式调整和控制，会占据用户大量时间。

（6）文档内容多、格式复杂时，编辑、保存都需要一定的等待时间。

（7）Word文件版本管理、内容比较、内容合并、内容恢复比较困难。

MBT文档模型化生成工具从Latex、Markdown、reStructedText等脚本生成文档技术中得到启发。升级、简化MarkDown，设计脚本，面向特定的应用目标，在使用上需要遵循一定的领域语言（方言）语法逻辑，就可以有针对性地加以自动化处理，以提高文档撰写工作效率。

（1）文档模型化，对文档要素建模，统一管理和处理过程。模型表格化，尽可能使得用户可用Excel录入。

（2）统一和简化文档样式，文档模型化生成工具鼓励简化文档样式。一篇文档通常只使用几种简洁的样式，包括：标题（1-6级）、目录、正文文字段落、插图（png、jpg、bmp、visio、UML图、Dot图等）、表格、编号列表项、无编号列表项、嵌入word文档块、嵌入其它文档、代码、公式。

（3）单位内部使用统一模板。设置模板服务器，当模板调整后，更新到服务器，工具自动从服务器下载最新的模板，生成符合要求格式、样式的文档。

（4）文档内容可复用，例如产品分级功能、产品基本情况、运行环境（测试环境、试用环境）、研制进度、人员安排、技术风险、技术先进性等内容，都可以作为文档块单独撰写，后续可以在各文档中包含使用。

（5）自动从标记的章节之间，生成组成、从属关系的UML插图、表格和相应的编号。

（6）通过脚本生成表格、图形、公式等文档要素，自动编号、指定引用标签。

（7）由于使用了基于模板的脚本生成文档技术，用户不再需要花费时间在对段落、插图、表格、目录、编号、页码、样式等文档要素要进行正确美观的控制。

（8）使用MBT脚本撰写文档，文档内容就是文本，可以使用内置DocEditor图形界面编辑器，也可使用用户常用的文本编辑器，如Editplus、UltraEdit、Sublime、VScode、Vim等软件。在文档内容很多的情况下，编辑效率更高，软件响应无延迟。

（9）文本文件版本管理、内容比较、内容合并、内容恢复容易。

（10）复杂的格式外部导入，如确实需要使用表格套表格、九宫格插图等复杂格式，可使用Word撰写好，通过指令插入。

（11）MBT可以作为中间文档格式。Word文件和PowerPoint文件可转换为MBT文件，通过MBT文件再转成其它格式。另外，一些系统需要生成文档，生成MBT文档比生成Word文档要简单得多。

2 文档工程化

MBT工具是实现复杂大型文档撰写工程化管理的核心环节。文档模型化（脚本化）使文档变成了类似软件代码的文本文件，因此可以借鉴软件工程理念、应用成熟的软件工程工具链，实现文档撰写工程化，极大提高文档工作的效率。具体的环节和对应的工具主要有以下几种。

需求管理，采集提炼用户需求，形成需求条目文档，指导文档撰写。

文档设计，确定使用的文档模板和文档内容框架结构，划分文档内容模块，将文档块，分配到不同的项目组成员，分工协作开展工作。

版本管理，用SVN或GIT版本管理工具，管理文档各版本，包括不同人员在不同时间、不同地点撰写的文档版本。

版本比较和合并，使用BeyondCompare、UltraCompare或WinMerge等工具之一，比较不同版本文档之间的差异，合并消除差异。

同行评审（Review），使用Review board、Gerrit、CodeStriker、Code Review Tool等工具之一，由项目组或各级负责人员实施文档检查和评审。

缺陷跟踪（Bug trace），使用JIRA、BugZilla、Bugtracker等工具之一，对发现的问题进行跟踪，直到问题解决。

自动构建，将一个组织内部的全部文档每天自动构建为目标文档，并收集分析构建过程中发现的问题。

采用GitLab 服务系统，用于文档仓库管理，使用Git作为文档代码管理工具，可一站式实现上述软件工程工具功能。文档在最后完成交付时，需要统一润色。

3 软件使用流程

（1）编写文档文本，保存为文档磁盘文件。

（2）输入文档磁盘文件到文档生成工具，工具通过解释器解释为文档结构，调用文档生成、UML绘制、Dot绘图、文档模板等模块或资源，生成目标文档（Docx、HTML、chm帮助文件、Qt帮助文件、pptx、pdf、xps）。其中，Docx格式是最终输出的文档，HTML格式用于快速察看文档效果，chm用于HtmlHelp联机帮助，Qt帮助文件用Qt软件联机帮助、PowerPoint用于演示汇报，pdf是Adobe提出的通用电子文档格式、xps是Microsoft提出的通用电子文档格式。

（3）用Word软件打开Docx文档（用PowerPoint打开pptx文档），对整个文档进行润色和校对。

建议在专门的一个目录中存放某个软件工程的相关文档。并使用版本管理工具对这些文件进行管理。纯文本格式的文档代码，利于版本管理和文本比较工具的使用。版本管理工具可使用svn或git，文本比较工具可使用Beyond Compare。

4 软件系统组成

文档生成工具由DocEditor图形编辑界面和控制台处理程序两部分组成。

一般情况下，用户只需要使用DocEditor编辑器即可。高级用户可使用控制台处理程序，实现一些自动化的文档处理调用。

4.1 图形编辑界面

文档生成工具提供了易用的图形编辑界面。

图 1 图形用户界面

左边是章节树，点击章节节点，可以在编辑器中选中相应的章节，右键菜单中，可查找章节，拷贝、粘贴、删除章节。

支持常用文档脚本的插入。支持常用文档脚本的插入。

支持在Windows资源管理器中，选中图像文件、Word文件、txt文件，拖放到窗口中。也可以将剪切板中的文本、图像直接粘贴到文档中。

图 2 插入常见文档要素

用户可选择一个其它编辑工具，如Editplus 4、UltraEdit、Visual Studio 2013、Visual Code、Sublime等，使用命令行指令生成，或者用文档生成工具编辑器打开再生成，获得输出结果文档。

图 3 生成菜单

文档生成工具提供了文档校对功能，能够检查文档中的中文文字错误。

图 4 高级工具

4.2 控制台处理程序

生成文档指令格式如下：

PrjDoc.exe xx.txt [xx.docx |xx.htm|xx.chm|xx.pptx|xx.pdf] switches

Switches文档类型开关: 实施方案 需求规格说明 概要设计 详细设计 测试大纲 测试报告 用户手册 帮助 通用文档等。如果没有指定文档类型，会从输入文件名称中推测文档类型。文档类型会添加到标题中，如果是通用文档时，文档标题不会添加“文档类型”字样。