Report Studio Documentation
Have you ever opened an existing report in Report Studio and blundered through the many components of the layout and queries wondering where the best place is to start trying to understand how it all comes together to form the output? If you’re a report developer, I’ll bet that you have. Report Studio is amazing in its capabilities, but the vast functionality can be a hindrance for developers having to maintain complex reports. Read on for tips to help document Report Studio reports so that the amount of time getting up to speed on the functionality of a report doesn’t take longer than the updating of the report. These tips are helpful for teams – so that other members of a BI team can gain a quick understanding of the report functionality – and even for yourself – so that the functionality you designed into a report comes back more quickly when you are asked to make modifications a year later.
Give objects meaningful names
You may be thinking, “Of course objects should have meaningful names, I don’t need to read a blog to know that!” Yes, of course we report developers know this, so let’s use this tip as a reminder to actually do it, rather than just know it. Most environments have their share of reports containing multiple data items named Data Item1, Data Item2, Data Item3 and multiple queries named Query1, Query2, Query3, Test Query, Prompt Query1, Prompt Query 2, Detail1, Detail2, Detail3. You may know what’s in that query or data item or on a page when you’re developing, but those generic names will not help you navigate the report the next time you are in it.
Meaningful names prove even more useful when there are multiple items to differentiate. Renaming Page1 to something indicative of its purpose is most useful when there is more than one page in a report, so that it is helpful to developers to quickly identify what is on each page. My point is, don’t kill yourself renaming pages on every one-page report – Spend your time naming items meaningfully where it will add value.
Documenting Queries
For reports that have only one query feeding the layout of the report, you can consistently name that query something like “Report”, and position it at the top of the queries, as anyone coming into an existing report will likely start here to gain an understanding of the report. For reports that have multiple queries in the layout, you can name the queries based on the report page names to quickly piece together how they’re linked.
Empty queries can be placed among the data queries to group and separate related data queries. For each empty query being used as an organizational tool, set the Name property of the query to a meaningful description for the group, surrounded by a repetitive filler so that the organizational queries are set apart from all of the data queries.
Names given to prompt queries should indicate that the query is used specifically for prompt information. When prompt queries are separated as indicated in the screenshot below, you may think prefixing the prompt query name with Prompt_ isn’t necessary, but you will find it useful to help you easily navigate to the correct option when selecting a query from the drop-down in the Properties pane of items like prompts and data containers.
Documenting Filters
Filters can be grouped using disabled filters. Insert a filter, add descriptive text to the expression surrounded by a repetitive separator, and then set it to Disabled.
Documenting Data Items
Data items can be grouped using dummy data items. Add a data item from the Toolbox tab, give it a descriptive name surrounded by a repetitive separator, and set the expression to something like a blank string or a zero. Insert as many dummy data items as necessary to group, separate and label the report data items.
More Detailed Documentation
Text can be added to the expression box of a data item or filter within the characters #/* and */#. This does not affect the expression. Adding comments in this nature can be used to document specific calculations, or to add descriptions or background information to specific items.
Developer Notes
Adding an additional page to a report and setting it not to render is a great way to maintain a change log within a report. This can be incredibly helpful when reports are maintained by multiple developers. Modifications made by each developer can be documented by entries on the “developer notes” page.
Your BI team could greatly benefit from these Report Studio documentation tips. Although documentation can be painful at the time of implementation, it is priceless when you delve back into a report months later. You will surely be grateful for it!
