Developing reports to make sense of project data can be a difficult task. IBM’s reporting tools enable users to report on the data from Rational Team Concert, Rational Quality Manager, and Rational Requirements Composer, but our clients often have trouble determining how to get the right data into the right reports. Through a collaborative effort between our clients and several Rational teams (incl. Support, Development, User Experience and Documentation), we explored the challenges and developed a plan to get all the necessary information into our users’ hands. Using tools to automate documentation of the data models, collect and expose SME knowledge about the product REST APIs, and filter the information based on goals, the team delivered a full set of guidance and reference material in the Information Centres that sheds some light on the black box of data. Ongoing efforts will connect the pieces using linked data, allowing fast and easy exploration of the data relationships.

1. IBM Innovate 2013
Smarter Documentation: Shedding Light on
the Black Box of Reporting Data
Karen Gosciminski
User Experience Designer, IBM Rational
kgoscimi@us.ibm.com
Kelly Raposo (co-author), raposok@ca.ibm.com
1951
© 2013 IBM Corporation

2. 2
Please note the following
IBM’s statements regarding its plans, directions, and intent are subject to change or
withdrawal without notice at IBM’s sole discretion.
Information regarding potential future products is intended to outline our general product
direction and it should not be relied on in making a purchasing decision.
The information mentioned regarding potential future products is not a commitment,
promise, or legal obligation to deliver any material, code or functionality. Information
about potential future products may not be incorporated into any contract. The
development, release, and timing of any future features or functionality described for our
products remains at our sole discretion.
Performance is based on measurements and projections using standard IBM
benchmarks in a controlled environment. The actual throughput or performance that any
user will experience will vary depending upon many factors, including considerations
such as the amount of multiprogramming in the user’s job stream, the I/O configuration,
the storage configuration, and the workload processed. Therefore, no assurance can be
given that an individual user will achieve results similar to those stated here.

3. 3
Reporting

4. 4
Reporting
IBM reporting tools
– Rational Insight & Rational Reporting for Development Intelligence
– Rational Publishing Engine & Rational Reporting for Document Generation
These enable users to report on data from a variety of IBM tools and some
3rd party tools
– Rational Team Concert
– Rational Quality Manager
– Rational Requirements Composer
– Rational TestManager
– Rational ClearCase
– Rational ClearQuest
– Rational DOORS
– Rational FocalPoint
– Rational Requisite Pro
– Microsoft Project

5. This presentation covers…
The challenge
The “Smarter documentation” effort
Next steps and how you can influence
the direction
5

6. 6
Background
Determining how to get the right data into the right reports is difficult
–Gaps in the extracted product data
–Mismatched terminology
–Numerous transformations
–Lack of information:
• Which data?
• What format?
• How is it transformed?
• What are the relationships across tools?

7. 7
“Smarter documentation” improvement goals
Help report authors and metrics engineers understand the data by
providing better information.
Whenever possible, automate the generation of information.
What we delivered:
–Conceptual diagrams
–Tutorials
–Multimedia (Videos, presentations, etc.)
–Task guidance
–Reference material

8. 8
Conceptual diagrams
Basic concepts
Data flow
Architecture

9. Diagram of data flow
9
Visual model of the data flowing from product to report.
Left  right follows data flow from UI  metadata model

10. Reference information
Reporting data dictionaries
Which metrics tables have
application data
Linked data warehouse & ETL
information and diagrams

11. Data dictionary overview
Operational Data Store only
(current data, not historical data)
Left  right follows data flow
from UI  metadata model
11
…
…

12. How do I use the data dictionaries?
“Reporting data dictionaries”
answers:
What does each column mean?
Why does the data change forms?
Which information do I use?
How can I used them for
development intelligence
reports
How can I used them for
document-style reports
12

13. Filtering the dictionaries
 Authors don’t need all the available data mapping information
 Select the type of report to hide columns you don’t need
13
…
…

14. Data flow through diagrams and dictionaries
14
…
Data flow and transformation

15. Data dictionary elements: UI Element and UI Field
15
…

16. Data dictionary elements: REST API
16
…

17. Data dictionary elements: XML to JDBC transformation
17
…

18. Data dictionary elements:
Data warehouse schema, table and column
18
…

19. Data dictionary elements:
FM model path, query subject, and query item
19
…

20. ETL model information
IBM Rational Insight
generates documentation for the ETL jobs.
20

21. Following data through the ETL documentation
Explore the Rational Team Concert model
21
To find where things are taken from Rational Team Concert..
and put into the data warehouse Operational Data Store (ODS)
(temporary table in this case)

22. Following data through the ETL documentation (cont.)
From temporary table to common table
22

23. Data Warehouse information
IBM Infosphere Data Architect
generates documentation for the
data warehouse.
23

24. Explore the ODS Request table
24
Details from the data dictionary..
help you find data and explore properties and related data.

25. Data warehouse table diagrams
25
…
Details from the data dictionary…
help you find the right tables and columns
in the data warehouse.

26. Build a query or a report
26
Details from the data dictionary…
help you find the right items in the
Report Studio or Query Studio browsers.

27. 27

28. Additional uses of reporting reference information
 Document-style reporting
Add data to Rational Publishing Engine document templates to design document-style
reports
 Troubleshooting
Use the documentation to determine what and why things are showing up in report output
(Example: Use Framework Manager to explore more details about the data)
 Understanding the models
Data modelers can understand all the models and how they relate and customize as needed
28

29. Potential enhancements and exploration
 Uncover product gaps
What types of data do people need to report on but can’t get?
 Fill information gaps
– Fill in missing information and
– Expand metrics tables information
 Task guidance
Teach authors how to use information to build and troubleshoot
– Samples
– Task guides
– Tutorials
 Link the data together
One click on data dictionary entry gets you all related info on one page
 Community contribution
Expose data so that the community can contribute additional knowledge
 Provide information and guidance about new capabilities and integrations
29

30. 30

31. Check out…
Peter Haumer’s session tomorrow morning:
RPT-1806 : A Guided Tour of Rational Reporting with Linked Data: Past, Present, Beta
Thu, Jun 6, 2013
9:45 AM - 10:45 AM
Swan 10
Rational Design Community
ibm.co/RationalDesignCommunity
Design Partner Programs - ratldpp@us.ibm.com
– Collaborative Lifecycle Management –Jeannette Gore jsgor@us.ibm.com
– Evolution of the Jazz Platform and Lifecycle Integration Adaptors –Jeannette Gore jsgor@us.ibm.com
– Reporting - Pennie Krotz pjkrotz@us.ibm.com
31

32. 32
Daily Apple TV giveaway
 Complete your session surveys online each day at a conference kiosk or on
your Innovate 2013 Portal!
 Each day that you complete all of that day’s session surveys, your name will
be entered to win the daily Apple TV!
 On Wednesday be sure to complete your full conference evaluation to receive
your free conference t-shirt!

33. 33
Acknowledgements and disclaimers
© Copyright IBM Corporation 2013. All rights reserved.
– U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
IBM, the IBM logo, ibm.com, Rational, the Rational logo, Telelogic, the Telelogic logo, Green Hat, the Green Hat logo, and other IBM products
and services are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or
both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these
symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may
also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at “Copyright and
trademark information” at www.ibm.com/legal/copytrade.shtml
Other company, product, or service names may be trademarks or service marks of others.
Availability: References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries
in which IBM operates.
The workshops, sessions and materials have been prepared by IBM or the session speakers and reflect their own views. They are provided
for informational purposes only, and are neither intended to, nor shall have the effect of being, legal or other guidance or advice to any
participant. While efforts were made to verify the completeness and accuracy of the information contained in this presentation, it is provided
AS-IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise
related to, this presentation or any other materials. Nothing contained in this presentation is intended to, nor shall have the effect of, creating
any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license
agreement governing the use of IBM software.
All customer examples described are presented as illustrations of how those customers have used IBM products and the results they may
have achieved. Actual environmental costs and performance characteristics may vary by customer. Nothing contained in these materials is
intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue
growth or other results.

34. 34
© Copyright IBM Corporation 2013. All rights reserved. The information
contained in these materials is provided for informational purposes only, and is
provided AS IS without warranty of any kind, express or implied. IBM shall not be
responsible for any damages arising out of the use of, or otherwise related to,
these materials. Nothing contained in these materials is intended to, nor shall
have the effect of, creating any warranties or representations from IBM or its
suppliers or licensors, or altering the terms and conditions of the applicable license
agreement governing the use of IBM software. References in these materials to
IBM products, programs, or services do not imply that they will be available in all
countries in which IBM operates. Product release dates and/or capabilities
referenced in these materials may change at any time at IBM’s sole discretion
based on market opportunities or other factors, and are not intended to be a
commitment to future product or feature availability in any way. IBM, the IBM logo,
Rational, the Rational logo, Telelogic, the Telelogic logo, and other IBM products
and services are trademarks of the International Business Machines Corporation,
in the United States, other countries or both. Other company, product, or service
names may be trademarks or service marks of others.

35. Video Extras
 Video of “Reporting data dictionaries” topic
 Video of exploring the ETL documentation
 Video of exploring the DW documentation
35

36. Documentation links
 Information Center Reporting data URLs
– Collaborative Lifecycle Management application data dictionaries
– Reporting data dictionaries
– Change and configuration management data dictionary
– Quality management data dictionary
– Requirements management data dictionary
– Data warehouse metrics populated by CLM application data
– Rational Insight ETL OOTB models documentation
– Rational Insight Data warehouse documentation
 Infosphere Data Architect documentation
– Product page
– Documentation
 Additional information on building reports
– Reporting tutorials
Creating reports with Query Studio
Build a simple parameter and list report in Cognos Report Studio
36

37. 37
Tutorials, videos, multimedia
YouTube videos
Tutorials on report authoring
Jazz.net media
YouTube playlists
• http://www.youtube.c
om/user/IBMJazz/vide
os?query=reporting
• http://www.youtube.c
om/playlist?list=PL41
F90AA10F4744B8
IBM Jazz videos:
http://www.youtube.com/user/IBMJazz/v
ideos?query=reporting
IBM RRDI videos:
http://www.youtube.com/playlist?list=PL
41F90AA10F4744B8
Videos and multimedia topic

38. Resources for getting answers and submitting bugs
 Jazz.net
 Jazz.net forum
 Open a work item for Rational Team Concert
 Open a work item for Rational Quality Manager
 Open a work item for Rational Requirements Composer
38