级别： 初级 Dr. Einar W. Karlsen (einar.karlsen@de.ibm.com), 高级信息工程师, Federated Integration Test team, IBM China Development Lab
Debra L.K. Johnson, 顾问软件工程师, IBM
2007 年 3 月 15 日 本文来自于 Rational Edge：为了证明与行业法规方针政策相一致，通常需要软件开发团队在整个项目周期的各个不同的方面来文档化他们的工作。这篇论文展示了如何使用 IBM Rational SoDA 与 Microsoft Word 的主文档和附属文档的概念，将复杂文档分解为更容易管理的部分。
法规遵循是一个与IT行业关系越来越密切的话题，无论遵从国际标准组织 (ISO)，Rational Unified Process®，或者 RUP®、V-Model、美国国防部 (DoD)标准，还是比如 Sarbanes-Oxley Act (SOX)这样的政府强制法规。IT 开发团队不断地证明法规遵循的方法之一是交付能够显示开发过程已经被引导为与相关开发标准相一致的文档。通常情况下，这种方法增加了跨越被采用的开发过程中的的工作流程、阶段，以及迭代来产生文档的需求。此外，在大的项目中文档可能仍然需要是正式的而且是可交付的。最后，全球分布式团队对能够支持分布式工作环境逐渐增长的通信要求的报告和文档需求也在不断增长。
要证明一个IT组织正依据这个公司和/或者组织的规则管理着它的业务，报告系统是此问题最主要的解决手段。工作在有法规遵循要求的环境中的IT组织必须能够证明他们已经计划、执行，并测试了这个应用软件与这些标准是保持一致的。这实质上要求以下这些能力，产生跨领域的报告，以及跨需求、模型、代码、测试用例和测试结果的文档。
在这篇论文在中我们将向您展示如何以一种灵活的和可扩展的方式，在 Microsoft Word 环境下利用 IBM Rational SoDA®来生成大量的文档。这种方法是建立在使用 Microsoft Word 主文档和附属文档功能的基础上的。这种情况不是生成一个大的报告，而是渗透到许多更小的报告生成中去。这样，每个报告都能够独立地重新生成。在 IBMdeveloperWorks的 Rational 专区提供有一个称做 SoDA Report Generator 的小应用软件，为了限制当整个主文档需要被重新产生时用户交互作用的数量，它允许一个用户在一个单一的步骤中重新产生组成主文档的所有报告。当产生巨大量文档的时候，大量相关的问题就会出现，比如选择生成或者模板参数化，因此我们也将接触到这些问题。如果您想要得到更多关于如何开发模板的信息，请参阅IBM developerWorks 上的练习。
自动化的文档系统：简单的概述
就像之前提到的一样，软件开发团队经常需要跨越被采用开发过程中的工作流程、阶段和迭代产生文档。在开发生命周期的特定区域中，所需的有代表性的文档在图1中有被说明。
图1：对应在标准的 Rational 统一过程图中的文档图标，表明在这个项目生命周期中这可能是需要文档的位置。
文档实质上是非常正式的，并且包括许多组成部分，比如标题版，目录表格，表格清单，图像清单，单个章节（在分段中又一次在结构上分等级），附件等等。因此一个文档常常由几个章节组成，并包括生成信息的混合物和手写的信息。这个章节的介绍可能由人工提供，然而接下来的详细信息可能从一个或者更多的开发工具中选择。一个文档被生成、交付、阅读、检查、修正，最后被储存（通常情况是）在一个配置管理系统中。所有这些表明这是一个十分耗时而且高强度的人工过程。主要暗示了产生这个文档的需求并不止一次，它在一个没有巨大数量数据规则的大项目中使用了人工的方法。
一个使用像 IBM Rational SoDA 一样的文档系统来产生报告的主要的优势是，它可以通过定制来满足文档标准，比如ISO 9000、SEI CMM、CMMI、Mil-Std-498，以及IEEE。由于信息是直接从这些工具中选择的（而不是通过人工拷贝），通过防止错误，缩短创建周期以及缩短审核周期来降低文档成本，因而保持了文档的最新状态。当数据发生变更，重新产生这个文档就变得十分简单，从而在保持重新产生文档低成本的同时提高了质量和信息的连贯性。对于大的项目，自然也需要产生一套更大的文档，和交付、检查和变更额外的时间。因此，确保那些文档与开发构架相一致变得十分重要，因为可能构架也发生了变更。在大项目的环境中和需要大量文档的环境中，灵活性和可扩展性就成了关注的焦点。仅仅因为在这个设计中的个别部分中有两个细节发生了变更，就要迫使用户为这个设计文档重新产生2000+页的文档，这当然不是一个合理的解决方案。
使用主文档和附属文档分割大的文档，并克服大文档的问题
让我们通过展示一个典型的SoDA模板开始，这个利用主文档和附属文档的模板还没有最优化。我们将改变这个模板使处理这个最优过程变得更加容易。这个模板的目的是产生一个统一的报告，包括一个标题页面，一个修正历史以及一个内容表格，接下来还有与这个项目设计相关的几章。前面的三章——“Scope”，“ Referenced Documents”，以及“Architectural Goals”——包含有用和相关的正文。剩下的章节利用了 Rational Software Architect。这些报告原理显示在最初的设计模板中，如图2所示。
图2. 初始设计模板
从第四章开始，SoDA 指令被开发用来抽取逻辑架构和每个包括在这个模型中的包/子系统的详细设计，，如图3所示。
图3：逻辑和详细设计模板
在拥有较大模型的项目中这个模板是不适用的，原因有以下几点：
- 这个模型包含相当多的包/子系统和类，导致生成的报告规模较大，超过了1000页。
- 执行也是一个问题。
- 模板的大小会使得结果难于被理解，因此几乎难以维护（或者调整）。
- 当在团队中工作时，拥有一个对每个文档都有详细说明的文档是不切实际的。
使这个模板可能不适用的一个最常见原因是，当这个设计模型发生变更时，许多项目都需要快速重新生成文档的能力。一个典型的情形是一些模型的变更（例如，使一个或更多的类图变得更完善）恰好发生在最终期限之前。此时强迫一个项目重新生成整个文档是不现实的，因为在这个模型的个别部分中的一些细节已经发生了变化。因此，通常在这个构架发生变更时会有一个可供选择的重新生成文档的指令。
这个方法是将这个模板分割成更小的部分使其能够被（重新）生成或者单个地编辑。我们将利用 Microsoft Word主文档和附属文档功能来完成这个工作，如图4所示。Microsoft Word主文档将包括静态的部分，比如标题页面，修正历史以及内容表格。此外它还包括对相应附属文档的参考，它依次包含着要么是由项目成员提供的自由形式编辑的文本，要么是以SoDA报告的形式生成的文本。如果SoDA Report Generator 直接运行，主文档和所有的次级附属文档都必须保存在相同的地址。
图4：主文档和附属文档
图4显示了把它分割成许多附属文档的文档。前面的三章——“Scope”、“ Referenced Documents”，以及“Architectural Goals”—— Microsoft Word 文档，并不包括任何SoDA指令。剩余的是基于SoDA模板生成的SoDA报告，并针对这个模板的特定部分。将一个复杂的SoDA模板分割成许多小的部分的好处是，对作者来说使其变得更容易管理，并可以生成完整的文档。这种方法的不利之处在于，与 Rational Software Architecture 模型连接的OPEN指令需要在每个SoDA模板复制。比如，这个模板“04 Logical Architecture.doc” 有一个OPEN作为初始指令（请看图5），因此接下来的任何SoDA模板都要有，比如“05 Detailed Design.doc”（请看图6）。
图5：逻辑构架的模板
图6：详细设计的模板
有选择的生成
当我们面临着一个相当大的模型时，我们可能要经历的是将单个的章节分割成附属文档，如上面所显示的那样，可并不能彻底解决问题，因为有些章节比如“Detailed Design”在这个相当大的模型中会产生非常多的页面。解决这个问题的唯一方法是将这个章节再进一步分割成更小的部分——比如，将包/子系统分割成簇，然后为每个簇创建一个附属文档。
对于SoDA，技巧性的解决方案是，在一个文本文档中给每个包命名，然后建立SoDA来选择这个信息，作为从这个模型中选择相关包的基础。切记：您要为每个有唯一名称的簇建立一个文本文档，以便SoDA能够辨认。在您创建这个SoDA模板之前，您还必须创建一个列举有这些包的文档，以便从这个模型中存取。在任何将要利用储存在这个文档中信息的SoDA REPEAT或者DISPLAY指令之前，您必须插入一个连接这个文档的OPEN指令，如图7所示。
图7：第一部分的设计模板
图7显示了连接一个称作“PackagesPart1.txt”文档的OPEN指令，它依次列出了这些数据所搜集的包/子系统的名称，比如，"User Services"和"Business Services。"这个OPEN指令之后，一个File_Record所需的REPEAT指令被插入，它在这个文档的每个记录中都会重复。
图8：使用文档中信息的 File Model Packages
附加的REPEAT指令：NestedPackage，如图8所示，在这个模型的“Logical View”的所有高层次包中进行迭代，迭代的条件是这个包的名字必须与这个文档记录的首个字段相匹配。这样，在SoDA报告生成时只有列在“PackagesPart1.txt”文档中的包才会被处理。当在“PackagesPart1.txt”文档中输入这个包的名称时，一定要确保以下一点：
- 这个文档中所列出的名称一定要与模型中包的名字相匹配（这包括大小写，拼写以及间距）。
- 有一换行插入在包名称的末尾。
紧接着的步骤就是产生这个报告，然后将它作为主文档的附属文档与主文档合并。然后，更多的包都可以加入到“PackagePart1.txt”文档中来。如果这些包/子系统生成的报告达到200－400生成页面时，定义一个新的簇是十分有利的。这样，可以拷贝这个模板并将它重新命名为“Detailed Design Part2.doc,”，然后变更新模板中这个文档的OPEN指令并指向一个叫做PackagesPrt2.txt的文档（它定义了第二个簇中的包），然后创建这个称作PackagesPrt2.txt的文档，如文章前面所显示的那样。在生成这些新的报告之后，将它添加到您的主文档中。这种方法非常灵活且有可扩展性，可以生成较大的设计文档。在设计文档时这个技巧是不受限制的，除了应用于大的需求规格和测试报告的情况。
除了对灵活性和可扩展性的要求外，此方法还能满足一些功能性的需求。通常情况下，项目想要按照某种逻辑的顺序打印出这些包/子系统。SoDA可允许模板使用构架的字母顺序或者数字分类，但是这种方法可能还不够完善，比如，当这些包/子系统必须按照一些其它标准来处理的情况就是例外。这种方法只是描述了这些包按照文本文档中所列举的顺序进行打印。除此之外，管理这个包是否包含在这个文档中就变得一目了然。如果不是，只需要确定这个包没有被列在这文档中（或者任何其它定义这个簇的文档）就可以了。利用这种方法您可以确保这个库或者其它低层次的实用包并不包含在这个最终报告中。这个方法的另一个价值表现在测试模板的时候：为了保证这个模板的功能性，与数据子集一起运行比与巨大的模型一起运行更快速更简单。您可以在这个模板被检验之后除去OPEN指令和相关的REPEAT指令，这个工作并不是很困难。
参数化的模板
每隔一段时间，模板的设计者们就需要对他们的SoDA模板进行参数化。例如，一个设计文档可能产生几个变量：一个总的文档仅仅打印出包，类图和类的描述，然后会有一个更详细的变量去包含了类细节，像操作、属性以及关系等。在这个上下文关系中，这个模板要维护几个变量是非常不切实际的，因为这对模板的维护十分不利。一个更好的解决办法是使用参数化模板——这意味着使用参数能够授予或者解除这个模板的特定部分的功能。
图9：详细设计信息参数的确定
要创建一个参数化模板，就要使用一个可以输入参数的文档。通过唯一的名称（第一个字段）和参数值（第二个字段）来识别这个文档中的每个参数，如图9所示。OPEN指令定义的连接器，FileSys_FileRecord，与“Parameter.txt”文档中的单一的一行相连接并被定义为唯一的键值。这个行通过唯一的键值来识别：在上面例子中的首个字段“ShowClassDetails”中。这个文档的第二个字段是参数值，随后可以通过LIMIT指令来重新找到它，最后用来识别类的详细资料是否在包含在其中。
图10：通过参数转换设计模板
无论这个类的详细资料是否被给定，它都被指定为与LIMIT指令相关的条件，如图10所示。如果这个文件记录中的第二个字段已经有了“Yes”值，那么这个条件也会是真。最终的效果是，与这个操作相关的信息也会由SoDA 生成。
大量报告的生成
当一个模板被分割成许多小的容易管理的部分，接下来的问题是如何生成它们。对于一个用户来说解决方案之一是打开每一个模板，然后通过调用SoDA>Generate Report，使其手工生成。当这些模板的数量很小时可以使用这种方法，但是当模板的数量急速增长，并且如果一个或者更多的模板不能够重新生成，那么这种方法就很可能会遭到数据不匹配。一个可选择的方法是利用专门适用于这个目的的 Visual Basic 应用软件。这个利用主文档的名称来生成所有在主文档的同一个地址中能够找到的SoDA模板。与此同时，SoDA也对其进程作出报告（但是实际上SoDA将在后台运行）。
图11：所有附带文档的生成
您可以从developerWorks 的 Rational 专区下载这个应用软件。这个软件是交互式的：它将打开这个模板并生成这个报告。SoDA打开的任何对话框都会显示出来——例如，那些处理安全的区域，用户需要登陆到一个域(比如，IBM Rational RequisitePro®或者IBM Rational ClearQuest®域) -- 并且在生成过程继续前进之前通过人工对其作出回应。
结论
在这篇论文中我们简单地展示了如何利用 Microsoft Word 主文档和附属文档的概念将复杂的基于SoDA的文档分割成更容易管理的片断。这种方法有以下几点好处：
- 文档变得更加容易开发、调整和维护
- 当开发团队面临着大量信息领域（比如，设计模式）时，这是一种可扩展性的方法
- 这种方法实现了将手写文本与生成文本混和起来的可能性
- 支持团队开发，因为每个附属的文档都可以单独地编辑（或者生成）
参考资料
作者简介  | 
| | Einar Karlsen 有20多年的软件开发工具和方法论的经验。他一直专注于研究、开发、项目管理以及咨询方面。他在德国不莱梅大学获得了博士学位，主要研究 case 工具的整合。他已经在 IBM Rational 工作了八年，支持客户对 Rational Apex、Rational Suite，以及 IBM Rational 软件开发平台的使用。 |
| 
| | Debra Johnson 从事电子学/软件行业已经有20多年。她曾做过测试基层监管、程序员、支持工程师、教师、技术撰写者、维护技术人员、教育课件开发者以及市场工程师。她已经在Rational 软件工作了九年，作为顾问工程师从事 SoDA、ProjectConsole 和市场的技术支持。目前她是 Rational Portfolio Manager 、Rational SoDA 以及 Team Unifying Platform 工具的市场工程师。 |
对本文的评价
| 
