Entries in Documentation
(2)

Overview: It’s common for companies to consider moving from another BI platform to Microsoft BI in order to reduce licensing costs, to take additional advantage of familiar tools, or to expand the body of workers capable of developing and supporting the Microsoft BI system. Following are some considerations when embarking on such a project.

Fact-Finding about Existing Reports

One of the first things you may wish to tackle is creating an inventory of reports to be converted. Good thinking. You may want to do this in parallel with some of the other items listed in the other sections.

Consolidation opportunities (for example, could 8 reports be consolidated to 1 with use of appropriate parameter selections?)

Level of complexity for each report (so that perhaps you can try to start with easier reports before tackling more difficult ones)

Interactivity requirements for each report (such as hyperlinks, drill-down, drill-through)

Decision of which reporting tool is most suitable for each report (SSRS and Excel and Power View and PerformancePoint all have their particular strengths)

Any cosmetic changes, improvements, or fixes permitted during conversion (if any changes are permitted during conversion that is)

Export requirements (this may drive decision on which reporting tool in the Microsoft BI toolset is most appropriate)

Subscription and alerting requirements (this may drive decision on which reporting tool in the Microsoft BI toolset is most appropriate)

Planning - BI Change Management

This section includes some of the more broad items to consider which can affect the scope and timing of the project.

Identify business rules from the previous toolset's metadata layer (here we are looking for logic embedded in another reporting tool’s metadata layer that needs to be replicated in ETL or elsewhere in the BI system – reproducing a Business Object Universe or a Cognos Framework Manager Model can be done with the BI Semantic Model, but it could take you by surprise and expand the scope & the schedule)

Identify data movement and ETL processes used by the previous toolset (here we are looking for any data sources that will no longer exist, or need to be replicated in the new system)

Understand security constraints for report access and data access (obviously very important – how much work this is depends on the particulars of your environment and the role the old BI system may have played with regard to security)

Develop process for testing & validating converted reports (is a comparison of new results vs. old results acceptable for testing, and does the testing require sign-off from a functional user?)

Determine if an automated conversion tool will be used, or if all reports will be redesigned from scratch (this is a big decision – no tool can convert every single report 100% perfectly, but it might save some time especially for basic reports)

Identify needs and requirements for governance, auditing and change management (such as approvals required and version history to retain, among many other things)

Planning - BI Training and Documentation

You can’t spend too much time on training and documentation. Trust me on this.

Determine how report developers will get trained on new set of tools (perhaps a combination of classroom training, on-the-job training, and assistance from a consulting firm that specializes in Microsoft BI)

Preparation for ongoing monitoring of query loads from new system and resources required to continue to monitor

Plan for how Self-Service BI will complement the Corporate BI system, if applicable

ROI and Cost/Benefit of New BI System

This type of analysis can be difficult. The organizations that do formal ROI and payback calculations already have formulas to do this, so I’ll just list a few things to consider with a BI system.

Costs: Include things like hardware, software licensing, cloud services, consulting services, IT support time, developer time, administrator time, time invested in training, ongoing software maintenance costs, etc

Benefits: Include things like cost savings, improved productivity, increase in sales, increase in customer retention, new capabilities, increase in agility, support for strategic goals, faster access to information, broader access to information, etc

Strategies for User Adoption of New BI System

Here you want to consider things that will encourage adoption of the new system. If a user has a poor initial experience with a system it can take a long time to win them over again.

Communication plan (such as timing of rollout, what is expected during testing cycles, schedule of reports to be converted, what users should do during the interim)

Support plan (first level support, second level, and if “power users” will get involved with support at all)

Training plan (if applicable – at a minimum, some helpful documentation is usually a great idea)

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:

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:

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.