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

本文主要是介绍MBT文档模型化、工程化生成工具用户手册 30倍效率文档撰写工程化方法 A model based document builder,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

MBT文档模型化生成工具用户手册

30倍效率文档撰写工程化方法

A model based document builder

  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文档要简单得多。

  1. 文档工程化

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

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

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

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

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

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

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

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

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

  1. 软件使用流程

(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。

  1. 软件系统组成

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

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

    1. 图形编辑界面

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

图 1 图形用户界面

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

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

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

图 2 插入常见文档要素

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

图 3 生成菜单

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

图 4 高级工具

    1. 控制台处理程序

生成文档指令格式如下:

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

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

这篇关于MBT文档模型化、工程化生成工具用户手册 30倍效率文档撰写工程化方法 A model based document builder的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/347694

相关文章

Java 中的 @SneakyThrows 注解使用方法(简化异常处理的利与弊)

《Java中的@SneakyThrows注解使用方法(简化异常处理的利与弊)》为了简化异常处理,Lombok提供了一个强大的注解@SneakyThrows,本文将详细介绍@SneakyThro... 目录1. @SneakyThrows 简介 1.1 什么是 Lombok?2. @SneakyThrows

判断PyTorch是GPU版还是CPU版的方法小结

《判断PyTorch是GPU版还是CPU版的方法小结》PyTorch作为当前最流行的深度学习框架之一,支持在CPU和GPU(NVIDIACUDA)上运行,所以对于深度学习开发者来说,正确识别PyTor... 目录前言为什么需要区分GPU和CPU版本?性能差异硬件要求如何检查PyTorch版本?方法1:使用命

Qt实现网络数据解析的方法总结

《Qt实现网络数据解析的方法总结》在Qt中解析网络数据通常涉及接收原始字节流,并将其转换为有意义的应用层数据,这篇文章为大家介绍了详细步骤和示例,感兴趣的小伙伴可以了解下... 目录1. 网络数据接收2. 缓冲区管理(处理粘包/拆包)3. 常见数据格式解析3.1 jsON解析3.2 XML解析3.3 自定义

SpringMVC 通过ajax 前后端数据交互的实现方法

《SpringMVC通过ajax前后端数据交互的实现方法》:本文主要介绍SpringMVC通过ajax前后端数据交互的实现方法,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价... 在前端的开发过程中,经常在html页面通过AJAX进行前后端数据的交互,SpringMVC的controll

Java中的工具类命名方法

《Java中的工具类命名方法》:本文主要介绍Java中的工具类究竟如何命名,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友参考下吧... 目录Java中的工具类究竟如何命名?先来几个例子几种命名方式的比较到底如何命名 ?总结Java中的工具类究竟如何命名?先来几个例子JD

Spring Security自定义身份认证的实现方法

《SpringSecurity自定义身份认证的实现方法》:本文主要介绍SpringSecurity自定义身份认证的实现方法,下面对SpringSecurity的这三种自定义身份认证进行详细讲解,... 目录1.内存身份认证(1)创建配置类(2)验证内存身份认证2.JDBC身份认证(1)数据准备 (2)配置依

python获取网页表格的多种方法汇总

《python获取网页表格的多种方法汇总》我们在网页上看到很多的表格,如果要获取里面的数据或者转化成其他格式,就需要将表格获取下来并进行整理,在Python中,获取网页表格的方法有多种,下面就跟随小编... 目录1. 使用Pandas的read_html2. 使用BeautifulSoup和pandas3.

Spring 中的循环引用问题解决方法

《Spring中的循环引用问题解决方法》:本文主要介绍Spring中的循环引用问题解决方法,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友参考下吧... 目录什么是循环引用?循环依赖三级缓存解决循环依赖二级缓存三级缓存本章来聊聊Spring 中的循环引用问题该如何解决。这里聊

Java学习手册之Filter和Listener使用方法

《Java学习手册之Filter和Listener使用方法》:本文主要介绍Java学习手册之Filter和Listener使用方法的相关资料,Filter是一种拦截器,可以在请求到达Servl... 目录一、Filter(过滤器)1. Filter 的工作原理2. Filter 的配置与使用二、Listen

Pandas统计每行数据中的空值的方法示例

《Pandas统计每行数据中的空值的方法示例》处理缺失数据(NaN值)是一个非常常见的问题,本文主要介绍了Pandas统计每行数据中的空值的方法示例,具有一定的参考价值,感兴趣的可以了解一下... 目录什么是空值?为什么要统计空值?准备工作创建示例数据统计每行空值数量进一步分析www.chinasem.cn处