Advanced Report Documentation

Why are reports in big corporations so difficult to understand? Is there a way to effectively document them and make them more understandable for the business user?


Where we got up to last time…

In my previous blog I described some basic steps a corporation can take to get the most out of its reporting platform. Let's say that the corporation has done just that and succeeded in completing the first stage of the report documentation process I outlined. Great, the management is happy, the project has been successful, the money invested into the documentation of the company's reports is no longer considered wasted. The next question is, what next? Where exactly should the company direct any new report documentation budget? I hope this blog will help you make this decision.


What's the goal?

The key recommendation here is to analyse thoroughly what should be improved and whom should benefit from further investment. I offer a few common situations below, together with their proposed solutions. You should assess how important the problems described are for you and choose your primary goal accordingly.


Situation #1

Is your communication about your reports still chaotic? Are the report stewards overwhelmed by questions from users? And are the answers they're giving, although repeated, unable to be shared because they're written in emails or given in phone-calls?


Make the tool used for report documentation, the Report Catalogue, the single communication channel for the delivery of explanations and answers to questions about reports, throughout the company. 


Situation #2

Is the main problem facing report users either not being able to understand or misunderstanding phrases and terms in the reports (e.g.the titles of reported variables etc.)?


Create a company business dictionary that contains and defines the terms used in the reports. Specifically identify the most frequently used reports and set out to define clearly the items reported in them. Buy technology which enriches the reports (which highlights, directly on the report's pages, terms which have been defined in the dictionary -  allowing users to see easily what they can find definitions for).


Situation #3

Are reports widely mistrusted and does this mistrust stem from inadequate data-quality or a lack of information about data-quality?


Publish the reports' data-quality information directly in the tool that provides the documentation - make it available directly on the report's page in the report catalogue.


Situation #4

Are report users complaining that they don't have enough information about changes being made to their reports and that they don't get any notification about how and when these changes are being planned?


For each documented report gather together information about its users and bind the list of users directly to the documentation. The tool for report documentation should be able to notify the users from the list automatically when the documentation page changes and the report stewards should use report documentation pages to announce planned changes.


Situation #5

Is the report's documentation insufficient for data-analysts and report developers?


Implement the company data dictionary - a knowledge-base that documents the data structures available in the company's data-warehouse and other data-stores and link the explanations in the report catalogue and business dictionary to the data dictionary.


Notes to the table

Each row of the table above contains a reference to a feature of the Report Catalogue. These features can be rather difficult to imagine if you haven't actually encountered a report documentation tool or our Report Catalogue before. So here's an illustrated explanation of what the terms or phrases mean:

Single communication channel

  • This means that all the information concerning the company's reports, including users' questions and answers, should be moved from emails to the Report Catalogue.
  • When a change is being planned to a report - the Report Catalogue.should be used to publish a notification about it - not email.
  • A report's users should be able to ask their questions and receive answers from the report owners / stewards directly in the Catalogue.

The enrichment of reports

  • Users in every corporation have to work with multiple IT applications. Report Catalogue provides an overview of a company's reports but it is a little cumbersome for users to be constantly switching between windows once they've found the report they want. That's why we suggest that when a user is working on a report and needs more information about the terms in it, it'd be ideal to provide these explanations and definitions directly in the reporting platform the user is working in (e.g. in Cognos, Business Objects, Microstrategy etc.). We call this "enriching".
  • By "enrich" I mean highlighting directly in the report, what terms are defined in the Business Dictionary and thus show users directly where an explanation has been provided and where it can be found.


Data-quality information

  • This is usually a bit of a more difficult project. However, each corporation usually has at least a part of the information concerning the current data-quality of their reports somewhere. The results of the data transformations used to calculate a report's figures are often sufficient to get an indication of an individual report's data-quality.
  • If a company publishes the results of the related data-transformations directly on each report's documentation page, users can automatically obtain a very good indicator of its current data-quality.

Data dictionary

  • It's actually quite easy to automatically create, build and update a web presentation of the data-structures in a DWH and other data-sources. Usually these systems are databases so a web presentation of the DB metadata retrieved from the information scheme of the DB can be generated automatically.
  • More about data dictionary.
  • More about connectors.


The next step

By outlining solutions to these potential problems, I hope I've helped you see what's really the biggest difficulty you're currently facing. An overview of problem areas and assessing them from the point of view of the different user-groups and company's business targets is indeed a substantial starting point. However, be careful about the actions you decide to take. In the Czech language we have a saying "Don't chase more than one rabbit at the same time". The biggest problem with building up the report documentation in any corporation is the naturally low priority that such a task receives. Almost any pressing issue can obtain a higher priority than it. Thus any project that sets out to improve documentation quality is prone to be prolonged or understaffed. So it's best to plan with small actions which have clear and tangible results. Then, when the goals have been achieved, implement some good internal marketing about them, present them to users, gather their feedback, breath in and out deeply, update your overview of problems and plan your next step.