Documentation: everyone’s favorite thing to do on a project, right? Especially the developers – they can’t 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 it’s useful then it’s 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!), here’s 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…

Typically I state the audience and purpose at the top of each document, just before the executive summary if it’s 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 it’s just in someone’s 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 it’s 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 don’t 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 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 report—name 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

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 won’t 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 there’s some overlap in this document from the requirements, the Report Definition can continue to be updated over time whereas the requirements typically aren’t 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, don’t 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
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, I’d sure appreciate if you’d leave me a comment.