Best Practices for Documenting Report Studio Reports

Synopsis:

Three methodologies for documenting Report Studio reports.

Overview:

Reporting tools like IBM Cognos Report Studio do not naturally provide a means of documenting and commenting procedures like traditional programming languages do. As a result, once a report has been created, it may be difficult to follow the logic and design of the original report, modify it, or reverse-engineer how it works. Additionally, the lack of documentation makes it difficult to determine how and why a report was built and what specific techniques were used to create it.

Using simple techniques and some Report Studio syntax, you can easily add comment statements and documentation a report that provide an bread crumb trail detailing how and why a report (and the different parts within it) were constructed.

This article discusses three different and complimentary techniques of documenting Report Studio reports by including:

A) Comment Statements in Data Items/Expressions
B) Overall Report Comments and Overview
C) Data Item Comment Sectioning

A) Comment Statements in Data Items and Expressions

Most correctly named data items are essentially self-documenting because of the naming convention they use when published in a package (e.g. [Country], [City] etc.). Author-created calculations, however, especially those involving nested functions, can be confusing or unclear to anyone aside from the original author. [ See Note a) below ]

Using the built-in Cognos macro syntax and special comment characters, you can document any data item or author-created expression using opening and closing pound sign characters (#) with comments entered between the characters “/*” and “*/”. Comments can be as long as necessary and can cover multiple lines. The example below shows the comment in black and the expression itself in red:

B) Overall Report Comments and Overview

A major omission of most software developers is the lack of documentation of how a program works and when, why, and by whom it was created. Fortunately, you can add this information with minimal effort using the following simple technique.

Start by doing the following:

1) Go to the Query Explorer and click Query1
2) Drag and drop a Query Calculation object from the Toolbox pane into the Data Items pane:

3) Name the new data item REPORT COMMENTS.
4) Type the following text (or something similar) with all comments enclosed within single quotes:

The best practice recommendation is to name the data item REPORT COMMENTS and place it at the top of the Data Items pane for easy identification:

For consistency and as a best practice, all authors in your organization should employ this structure and use a standardized format for it (e.g. similar to the above) in every report that is created.

C) Data Item Comment Sectioning

Complex reports often have multiple data items that may contain several calculations created by the author(s). After the report is created, going back to locate, modify, or de-bug the report can be confusing when many disparate data items are randomly ordered in the query.

If you neatly order all co-related items in the Data Items pane, additional modifications to the report become easier to make because the data items are logically laid out.

This technique is related to B) above, but the documentation appears in the name of the data item, instead of in its contents.

To organize your data items in this way, do the following:

1) Drag a Query Calculation object from the Toolbox pane into the Data Items pane.
2) Name the new data item based on your desired section (see the image in step 5 below).
3) In the expression editor, add a space surrounded by single quotes (i.e. ‘ ‘) to show that there are no comments in the data item.
4) Repeat as needed for additional sections.
5) Drag and drop all related data items under their appropriate section name.

NOTES:

a) In Item A) even the original report author may not remember the details of a report’s structure. Complex expressions may be brilliant and elegant when created, but confusing and hard to decipher weeks or months later, even by the person creating them.
b) Item B) above can be read into and displayed on a report when report authors run it. This technique allows authors to quickly see all the details of the report simply by running it and stops them from having to open the report in Report Studio and look at the comments..
c) In Item C) the data items representing section names have no value, just single quotes around a space as a placeholder to create the data item name.