Generating compliance documentation using IBM Rational Publishing Engine: Part 2. Document design and layout

Part 2 in this series of four articles about using the IBM® Rational® Publishing Engine to generate compliance-relevant reports shows how to decompose large and complex reports into smaller, more manageable templates. It also covers developing reusable templates and creating a standard layout that adheres to your company's style guidelines.

Dr. Einar W. Karlsen (einar.karlsen@de.ibm.com), Solution Architect, North-East Europe, IBM

Author photoDr. Einar Karlsen has more than 25 years of experience in the area of software development tools and methods. He has been with the IBM Rational division for 13 years, supporting customers in the use of Rational software, covering aspects related to demonstrating compliance by using report generation tools, among others. He works in Germany.



29 November 2011

Document composition

IBM® Rational® Publishing Engine supports creation of complex documents perfectly. The concept of document specification allows a document to be composed from several templates that can be developed, tested, deployed and maintained separately.

For example, the screen capture in Figure 1 shows the document specification that was used to generate the software development lifecycle report in Part 1 of this article series. It contains templates for the following sections of the document:

  • Title page, table of contents, list of figures (FrontPages.dta template)
  • Written introduction (Introduction.dta) from Microsoft Word
  • Microsoft Excel-based risk list (ExcelRiskList.dta)
  • IBM® Rational® DOORS® stakeholder and system requirements (DOORS.dta) in text format, as well as subsystem requirements (DOORS2.dta) in table format
  • IBM® Rational® Rhapsody® use case model and requirements model (UseCaseModel.dta, ReqModel.dta)
  • IBM® Rational® Quality Manager test plans and test results (RQMTestPlan.dta)
  • IBM Rational Quality Manager work items (RQMWorkItems.dta)
Figure 1. Document specification
Document specification tab shows a list of templates

Designing for reuse

IBM Rational Publishing Engine features can help an organization establish publication standards and reduce costs of producing reports by defining a library of highly reusable templates. Most of the templates in the sample document have been made generally applicable by defining information such as document title, project name, section heading, author and date in terms of variables that can be instantiated with actual values as part of the document specification. For example, both the title page and the introduction of the sample report shown in Figure 2 are generally applicable due to use of parameterization, or specifying the parameters.

Figure 2. Reusable title page and introduction
Title page and introduction of sample documentTitle page and introduction of sample document

Figure 3 shows an excerpt from the FrontPages.dta template and the use of external variables (Title, Project) to render information such as the document title and project name in Paragraph elements.

Figure 3. Template parameters defined for the title page
Text element with variable defining section title

The actual values of those variables are provided as part of the document specification by setting the value property, as shown in Figure 4.

Figure 4. Definition of actual values
Properties table with Property and Value columns

The next template (Introduction.dta) includes information from a Microsoft Word document. Again, parameters in the template have been used to ensure a high degree of reusability. As Figure 5 shows, the path of the Word document to be included has been defined in terms of the WordDocPath variable in the Include File element of the template as shown in Figure 5.

Figure 5. Inclusion of a Microsoft Word file
Include the file element with the Word file path

The actual path of the Microsoft Word document can then be specified in the document specification, and can vary from one document to another. The template can therefore be used to import any kind of Microsoft Word file, provided that the text from Word is supposed to appear directly following the section title.

Figure 6. Stakeholder and system requirements
Generated output that contains DOORS requirementsGenerated output that contains DOORS requirements

The DOORS.dta template is another instance of achieving a high degree of reuse. This template has been used as a basis for generating the stakeholder requirements without rendering the attributes, as well as for the system requirements rendered with attributes, as shown in Figure 6.

Variables, such as PRINT_ATTRS and PRINT_TABLES, have been used to enable or disable printing of Rational DOORS attributes and tables, respectively, as shown in Figure 7. The template uses the PRINT_ATTRS variable in a condition to ensure that information regarding attribute values (in the container named Requirement Attributes) is rendered only if the value of the variable is True.

Figure 7. Using parameters to hide details
Filtering using an external variable and condition

Whether this is the case or not is controlled by defining the actual value in the document specification. This way, the template can be used for all Rational DOORS requirements, whether they are stakeholder requirements (no attributes rendered) or system requirements (some attributes rendered). If rendering of attributes is enabled, the template has been defined to iterate over all columns (query $4) and then print the column name and value.

Tip:
Providing metadata, such as the container name (Requirement Attributes), significantly increases the readability, and thus maintainability, of the template.

Figure 8. IBM Rational DOORS view
DOORS view with requirement text and attributes

Larger view of Figure 8.

The set of attributes rendered is controlled by the actual DOORS view being used. For example, the view in Figure 8 shows the Priority and State attributes for the system requirements but not the other attributes available for those requirements. The document specification has been configured to use this view to ensure that only those two attributes are rendered in the report, as shown in Figure 9. The actual view used is determined by the URI property of the DOORS data source. You can use the DOORS Data Source Selection Wizard shown in Figure 9 to configure the data source, including the URI, username, and password properties (among others).

Figure 9. Rational DOORS data source configuration
Wizard window in Document Studio

Larger view of Figure 9.


Document layout

Organizations that need to generate compliance-relevant documents usually have very specific requirements with respect to the actual layout of the document. For example, typically, the document must be generated with a title page, headers, footers and so forth, all aligned with company standards.

There are basically two ways to achieve this:

  • Define styles within a word processor source file, such as a Microsoft Word document
  • Define styles within the template

Define styles within a word processor source file

The most straightforward solution is to use a Microsoft Word outline to define the headers, footers and paragraph types according to your company's style guide. This Word outline is then used as stylesheet for generating the report. See Figure 10 where properties are set in the document specification to define the actual path of the Word output file and the stylesheet to use.

Figure 10. Configuration of Microsoft Word output
Properties for defining the Microsoft Word output

The relevant styles in the Microsoft Word template must have associated placeholder styles in the Rational Publishing Engine. These styles should then be used and associated with template elements to control the actual formatting of the elements. For example, in Figure 11, the document title has been defined to use the Title style. The actual properties (font, paragraph alignment, and so forth) do not need to be set in the template, but they can be. If they are not defined there, the associated style definitions in the Word outline file will be used.

Figure 11. Use of IBM Rational Publishing Engine styles
Setting Title as the style for a Text element

Another aspect of generating Microsoft Word as output is the use of macros (see the macro property in Figure 10). Rational Publishing Engine uses macros to post-process the generated document. The standard macro for that purpose is called rpe, and it basically makes sure that the table of contents, the list of figures or tables and such are updated and that referenced documents (such as the introduction) are imported into the generated output file. However, you can develop your own macros to use instead, if you prefer.

Define styles within the template

Another solution for ensuring that the generated output complies with your company's requirements or guidelines is to define the style headers and footers, for example, directly in the template by using master pages (see Figure 12).

Figure 12. Master page that defines headers and footers
Header element with an image and variable text

Larger view of Figure 12.

This solution will require you to repeat some of the work that you already did in the Word outline, but it has the advantage that the Rational Publishing Engine can more easily take full control over the information rendered (in the headers and the footers, for example), such as displaying data kept in variables or data extracted from the information sources. This is the solution that we adopted in the current set of examples, where the master page (Figure 12) renders the value of variables set in the document specification, such as Title and Section, along with additional elements, such as an image (company logo stored in a JPG file), Author, Page Number, and Total Page Number.

Tip:
A document can contain several master pages, and master page settings can be changed within a single template. For example, the FrontPages.dta template uses the master page called MPT (with no headers and footers) for the title page, but the other pages are set up to use the master page named MPN.


Reusable template fragments

To foster reuse of template fragments and to support organizations in establishing standards in their documentation, it is possible to declare reusable template fragments called snippets. You can declare a snippet simply by invoking the Template > Organize Snippets command. You will then be asked to enter a name, description and template file path for the snippet. After a template file has been defined as a snippet, it can be inserted into a template with a single operation. The snippet will appear as an element in the Palette view, similar to the way that predefined template elements such as paragraphs, tables, and figures do (see Figure 13). To insert the snippet into the current template, simply select the name of the snippet in the Palette view, position your cursor in the document template where you want the snippet to be inserted, and click.

You can declare a library of reusable components to ensure a standard look and feel across the various templates and to reduce the time needed to develop new templates. For this example, we used this feature to declare snippets for insertion of a master page, table and figure. Having done that, it took just a few steps to create the template in Figure 13, simply by inserting Demo Master Page and Demo Table snippets from the (extended) tool palette.

Figure 13. Use of snippets
Palette element for inserting a custom table

Larger view of Figure 13.

Note:
This template will be completed in Part 3 of this article series by inserting queries to extract information from DOORS.


Summary

This article demonstrated how you can use IBM Rational Publishing Engine to decompose large reports into smaller, more manageable units, ways to design templates for reuse, and to set up templates to be comply with your organization's standards. It covered these topics in particular:

  • Document specifications to split a large document into smaller, manageable pieces
  • Variables to develop parameterized, reusable templates and to enable or disable rendering of specific details in a report
  • File inclusion elements to import written text from Microsoft Word into a report
  • Styles in Microsoft Word and Rational Publishing Engine to achieve a specific layout
  • Master pages to define headers and footers that adhere to your company's style guide
  • Snippets to establish a library of reusable templates that enforce a standardized look and feel and, at the same time, reduce development and maintenance costs

What's next

Part 3 of this series shows you how to use the Rational Publishing Engine to create reports by taking information from several information sources, including the ability to follow traces from information in one tool to data managed by another in the same document. The template created by using snippets will be completed by inserting queries to extract information from DOORS. Part 3 also shows you how to report on information managed by other software, such as Microsoft Excel. In addition, you will see how you can use other options, such as JavaScript, to control the color of information rendered in the report.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=776382
ArticleTitle=Generating compliance documentation using IBM Rational Publishing Engine: Part 2. Document design and layout
publish-date=11292011