03/01/2014 SQL Chick - Microsoft BI Blog

www.sqlchick.com/entries/2011/5/7/documenting-a-reporting-project.html?printerFriendly=true 1/5
Documenting a Reporting Project
Saturday, May 7, 2011 at 9:20PM
Melissa Coates in Documentation, Reporting Services, SQLServerPedia Syndication
Documentation: everyones favorite thing to do on a project, right? Especially the developers
they cant get enough of it. Okay, okay, back to the real world. Technical documentation is thought
of as a necessary evil by most IT folks. In my opinion, if its useful then its great. What makes it
useful? Read on.
I was asked on Twitter how I go about documenting my SSRS projects. Seeing as I have a lot more to
say than 140 characters (what a shocker!), heres my thoughts & experience on the subject. Thanks
to Cody Konior ( Blog | Twitter ) for the inspiration.
Summary
This entry proposes the following types of documentation for a reporting project:
For the overall reporting project
1. Inventory of Reports {updated as needed}
2. Report Design Guide {updated as needed}
3. User Guides and Tutorials {updated as needed}
For individual reports
1. Requirements {temporary}
2. Report Definition {updated as needed}
3. Testing Results {temporary}
Keep reading for more information on the above 6 suggestions
Purpose & Audience
When deciding what documentation you need, the first thing to ask is: Who is the audience for this
document? Knowing the audience helps leads into what the purpose for the document is. For
example, documentation could be used for:
Reference Guide (For yourself or others? As part of a library of reports? As part of a
standardized set of reports?)
Training or Tutorial (Perhaps someone else will support the reporting project? A new
employee in a similar role as you?)
Communications and confirmations with business users
etc
03/01/2014 SQL Chick - Microsoft BI Blog
www.sqlchick.com/entries/2011/5/7/documenting-a-reporting-project.html?printerFriendly=true 2/5
Typically I state the audience and purpose at the top of each document, just before the executive
summary if its a very long document.
Goals of Documentation
I tend to have the following goals for documenting a reporting project:
Standardization. When certain things are standardized, I like to have them listed out. The
Report Design Guide is an example of this.
Efficiency. Provide info about business rules/calculations/derivations without having to open
up the report (or an underlying stored procedure, or function, etc). (As a sidenote:
sometimes when I am documenting/explaining something, it dawns on me that I have a hole
in my logic it really does force you to think through your code.)
Understanding. Explain why certain decisions were made. The goal here is usually to get
this type of information on paper otherwise its just in someones head.
Useful Types of Documentation for the Overall Reporting Project
1. Inventory of Reports
The report inventory lists each report, as well as other metadata about the reports. This is a great
candidate for a data-driven solution (as opposed to a manually maintained document). Table(s),
SharePoint Lists, or another data-driven mechanism to store the report metadata works really well
if its associated with the report header (ex: Title; Subtitle) and/or footer (ex: Path; Version #), you
are forced to maintain this inventory which serves as an added bonus. Things you may want to
include:
Report title
Report number
Report description
Path of report (relative URL)
Intended audience
Version number
Support contact
Active (Y/N)
2. Report Design Guide
A Report Design Guide, or whatever you choose to call it, is your standardized list of things a report
developer should know in order to ensure the same look & feel is maintained throughout the entire
set of reports. What we dont want, even in a small organization, is for one person to develop a
report with brown & maroon colors in a 12 point font & hyperlinks underlined, and another person
to develop with blue & tan in a 10 point font & hyperlinks in blue but not underlined you get the
drift. In my opinion, a consistent look & feel - both cosmetically & with how interactivity takes
place significantly enhances the usability of reports.
This type of documentation may be subdivided up by different types of reports: tabular, chart/graph,
and scorecards. You might choose to include items such as:
BIDS solution and project guidelines (i.e., how projects are logically divided; project naming
03/01/2014 SQL Chick - Microsoft BI Blog
www.sqlchick.com/entries/2011/5/7/documenting-a-reporting-project.html?printerFriendly=true 3/5
conventions)
Data access guidelines (SSRS embedded code; stored procedures; views) (See this entry for
more considerations)
Standardized report header contents (ex: title; subtitle; parameter values selected; company
logo) and placement of each
Standardized report footer contents (ex: page 1 of x; report path; datetime executed; name of
user executing reportname is particularly helpful if data is confidential) and placement of
each
Requirements of a Data As Of date (i.e., to let user know age of the data being displayed)
Inclusion of logo (example: include on more formal or external reports; omit on internal
reports)
Report naming conventions
Report numbering conventions
Font name, size, and weight (header, footer, table header row, tabular data, subtotals, grand
totals, etc)
Vertical alignment (ex: table header row is bottom justified; all other data is top justified)
Horizontal alignment (ex: amounts are right justified; text is left justified; some integers may
be centered)
Usage of borders (ex: suppress vertical borders but display horizontal borders for readability)
Parameterization standards (ex: dates sorted descending; usage of defaults & if they may differ
per sets of users; standard parameter labels)
Orientation default (portrait or landscape)
Physical page size (height, width, and margin defaults for printing purposes)
Interactive page size (if allowed to differ from physical page size)
Report properties which should be completed (ex: author and description)
Formatting of hyperlinks (ex: blue and underlined)
Standardized no data message and its formatting (a Tablix property)
International currency, date, or language considerations
Rounding (ex: if summary report, decimals may be rounded; if detail (drill-through) report,
display decimals)
Scaling (ex: to 10s or 100s or 1000s)
Conditional display of amounts (example: red if < 0)
Display of signs on debit and credit balances (i.e., should credits be shown as negative
numbers or not)
Display of percentages (how many decimal places)
Display of zeros (suppress 0 or display 0s; are hyperlinks enabled on 0 amounts)
Display of negative numbers (with parentheses or sign)
Usage of backcolor or shading on every other row
Usage of $ symbol (ex: just on grand total)
Drill-through behavior to another report (i.e., launch a new window or remain in same window)
How images are handled (in database, project, or embedded within individual report)
Usage of shared datasets for reusability among various reports (requires SQL Server 2008 R2)
Requirement to repeat table header row on each page of report and/or remain fixed when
scrolling (See this entry for how this is done)
Standardized usage of color, particularly for red/yellow/green indicators (ex: RGB values)
Standardized indicators utilized to display status or trend
3. User Guides and Tutorials
03/01/2014 SQL Chick - Microsoft BI Blog
www.sqlchick.com/entries/2011/5/7/documenting-a-reporting-project.html?printerFriendly=true 4/5
Some companies choose to publish things like Quick Start Guides, User Guides, or other types of
tutorials, to help users get started with a new system. These may or may not include hands-on labs
or exercises. This type of documentation could cover things such as:
Accessing the system
Login questions & security issues
System requirements
Navigation of screens, folders, libraries
Using toolbars
Printing
Saving
Exporting (ex: to PDF or Excel)
Searching
Frequently Asked Questions (FAQs)
Data dictionary
Glossary
How to create reports (if tools like Report Builder or Excel Services is offered in addition to
canned or menu reports)
Help desk or support contact information
Useful Types of Documentation for Each Individual Report
1. Requirements
Ideally, the requirements are handed to you & include all details needed to develop the report. If the
organization takes their requirements gathering process pretty seriously, it may also include use
cases. The contents of the requirements is so similar to item 2 next, that I wont list them here.
Read on.
2. Report Definition
I prefer an individual report definition file to be in the format of a quick reference guide, and as
short & to the point as possible. Although theres some overlap in this document from the
requirements, the Report Definition can continue to be updated over time whereas the requirements
typically arent in my experience. Also, the Report Definition ends up being a lot more detailed
(especially if you create it during development rather than after hint, hint). If you do have
something like a Report Design Guide (discussed above) in place, dont repeat those items here
just reference that one master document. Report-specific things you might want to include:
Owner of report
Subject matter expert(s)
Data source(s)
Fields (including where the source is, or if it should be derived)
Business rules
Calculations
Parameters (including defaults)
Filters
Grouping
Sorting
Page breaks
03/01/2014 SQL Chick - Microsoft BI Blog
www.sqlchick.com/entries/2011/5/7/documenting-a-reporting-project.html?printerFriendly=true 5/5
Intentions for printing vs. online viewing
References to embedded or external code
References to related database objects (stored procedures, views, functions)
Sample of the report (screen shot)
Security considerations
Intended delivery mechanism (run on demand vs. delivered by subscription)
Usage of caching and/or snapshot
Future maintenance tasks or manually maintained items
Relationship of report to a specific ETL process
Departures from the Report Design Guide (with a quick note as to why)
Change log (who requested what change & when; who executed the change)
3. Testing Results
This is essentially a checklist of the tests performed, and the pass/fail results. Depending upon the
procedures required in your organization, this could be some quick unit tests for accuracy &
functionality, or it could be a huge major deal that also includes system testing & integration testing
as well. Testing of an SSRS report may includes things like:
Data accuracy
Acceptable performance
Data level security accuracy
Functionality of report parameters
Export functionality
Print functionality
User acceptance
etc
Have fun writing your documentation! If you have any suggestions or additions, Id sure appreciate if
youd leave me a comment.
Article originally appeared on SQL Chick (http://www.sqlchick.com/).
See website for complete article licensing information.