Erin Dunmire
Business Analytics Specialist
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!
No comments:
Post a Comment