How do you document your reports?

Question

How do you document your reports?

chris-736523

SSC Eights!

Points: 928
More actions
December 30, 2009 at 1:54 pm

#215357

I'm working on an enterprise project, and it would seem that the only thing that isn't documented is the reports. We have lists of the necessary reports, but don't really have fundamental requirements of each of the individual reports.
Ideally, I'd like some sort of flow like this.
Report Requirements - Why do we have the report, what is it used for, and what does it need to do (all the way down to parameters, grouping, sorting, calculations, etc).
Report Specifications - How the report was built against the data that is available.
Report modifications - Change requests to alter the original report requirements or just get more granular.
Until now, we have really been flying by the seat of our pants, going to the business as needed.. but then it comes back to us because we designed the report according to a few individuals that of course is disputed by other individuals. I'd like to get to a more structured process.
Also, FYI. These are very complicated financial type reports, so the level of detail is almost endless.
Any suggestions???
Thanks,
Chris

Viewing 13 posts - 1 through 12 (of 12 total)

You must be logged in to reply to this topic. Login to reply

c00ler01 Ten Centuries Points: 1180 More actions · Answer 1

You already know (said) what you need to document. Sounds like you need the standard to follow. Come up with a structured documentation, give it to your work collegues to approve it. Once it's approved, all the work should be peer-reviewed to ensure that everybody follows the standard. If somebody didn't follow the standard, send it back until they get it right, otherwise it'll be a mess forever.

I believe that certain details of the report should be stored within the spec and kept else where (that document also should follow some sort of template).

c00ler01 Ten Centuries Points: 1180 More actions · Answer 2

In terms of modifications, you'll need to keep the track of the following:

1. Previous version of the report

2. Date when the change has occured

3. Person who made the change

4. Link to another document with the details why the change has been made.

chris-736523 SSC Eights! Points: 928 More actions · Answer 3

Thanks for the reply.

I do know what is needed, however, it is quite difficult to find a balance between having enough detail and something that a business user can read, understand, and approve.

I also get sick of other requirements documents that are so "top-to-bottom" and do not make much sense until you read the whole document.

I guess I will buckle down in word to see what I can come up with. Or maybe iRise. If anyone else has had good luck with a particular product made for documentation (besides word!) please let me know.

Thanks.

Happy New Year. 😀

becklery Hall of Fame Points: 3315 More actions · Answer 4

Here are the steps:

1. Go to Report on Report Manager

2. Click "Show Details"

3. Click "Properties" of the report you need to Export

4. Under "Report Definition", click on "Edit".

You will be able to either "Open" or "Save" the RDL file.

RAQ Report: Web-based Excel-like Java reporting tool[/url]

Jeff Moden SSC Guru Points: 1004339 More actions · Answer 5

chris-736523 (12/31/2009)
...however, it is quite difficult to find a balance between having enough detail and something that a business user can read, understand, and approve.

I resolved that issue a long time ago... I make the business user write such requirements and then have them work directly with the developer to ensure the report is developed correctly the first time. Saves on a huge amount of rework. It also saves on the number of reports to be created because a user knows that if they can't describe it or doesn't "have the time", neither can/do we. 😉

--Jeff Moden

RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
First step towards the paradigm shift of writing Set Based code:
________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

Change is inevitable... Change for the better is not.

Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)

chris-736523 SSC Eights! Points: 928 More actions · Answer 6

becklery,

Your response is quite lame. Download the RDL is your answer?

Maybe you are just trying to spam the forums with the link in your post?

Jeff,

I like your reply, that does apply for some areas of our business where individuals ask for reports, and it's quite effective at getting rid of those requests! But, my problem is that we are responsible for the report definitions for the broad reports (where it's the whole business that needs to take place in the requirements process).

Chris

mvee Hall of Fame Points: 3634 More actions · Answer 7

It may be a bit overkill, but we have 2 procedures in place:

1. we have a SSRS development sharepoint site and then we have a subsite for each major report.

a) in the main ssrs site, we have standard report information such as colors and fonts and general guidelines, templates to download, etc

b) in each subsite, we have specs for the report and a generic list of information such as who is the lead developer, who is the business owner, due dates, issues, modifications, etc

users know to use these sites and it seems to work ok, albiet, not perfect as people don't always post change requests, etc

2) we still use sourcesafe to store the rdls so that other developers can always download the latest version, etc. again, this is only as good as how well the lead developer keeps the sourcesafe file up to date. 😉

good luck.

-Megan

ricky.chauvin SSC Enthusiast Points: 162 More actions · Answer 8

Were currently contemplating a similar problem here and if your thinking the above is overkill you may think this is too!

I work in a production environment so its request, request, demand here.

Our idea for our solution is to set up an asp.net page with webpart each of which link to a report or "tool / toolset" this way through a customisation page the user can set up their own dashboard. This way the only requests are for new tools.

A small victory but a victory nonetheless.

r.stebbens 78867 SSC-Addicted Points: 407 More actions · Answer 9

Depending on what you want the documentation for you may want to add some initially hidden descriptive text to each report outlining what it does. you could make this switchable so that end users can also see that information, although a complex report can end up looking messy if there are lots of detail.

Developer, DBA, Pre-Sales consultant.

Cris E Ten Centuries Points: 1255 More actions · Answer 10

Requirements for me start with a business description in business terms so that no bad assumptions get made about how tools work or what data will or won't be included or if something can be done. This includes business defining the audience and security needs in their terms. Then you can get into tools, data sources, columns, breaks/groups, sorts and parameters and finally dig into security rules in IT terms. If there are calculations then those need to be laid out in detail. Provide spots to define charts and graphs,alternative calendars, foreign languages or specific output formats (ie PDF or XLS.) You may want to add a spot for testing and also make note of any unusual decisions or events that affected the final product.

You can have separate change control versions of this doc that only include deltas, who was involved in the request, the work and the testing, and if any tradeoffs had to be made.

One other thing to consider for the future is adding a report description into the original requirements template so while business is still sitting there they can help craft a short blurb that you can use for casual users. Most of the time they need a lot less documentation than you think.

Last point: in my humble opinion these docs are almost never searched or referenced except when something goes wrong, so maybe don't bother with a fancy system and stay with Word or Excel. If you have something on hand or there's a corporate standard then go ahead. But these have as much value of their value in CYA as anything else so they just need to be accurate, not powerful or integrated or whatever. MS file servers have the ability to search contents anyway, so simple might be better. YMMV.

[font="Arial"]Are you lost daddy? I asked tenderly.
Shut up he explained.[/font]
- Ring Lardner

amc-885860 SSC-Addicted Points: 493 More actions · Answer 11

Chris,

I am a newbie to BI and SSRS and I have been task to do the same exact thing you're trying to do now.

Go to this link for templates of this nature.

http://mike2.openmethodology.org/wiki/Category:Deliverable_Templates

This is the main page for 'Deliverable Templates'. Look under the letter "R" for the following:

1. Report Design and Protyping Deliverable Template

2. Reporting Requirements Deliverable Template

This might be what you are looking for. I'm curious to know what you think. Will you reply back to me to let me know. I would appreciate it. Thanks. amc@liq.wa.gov

Ben Wilson-179630 SSC Eights! Points: 998 More actions · Answer 12

we have a report spec document to complete for each report. The front cover has a change log which details the help desk ticket for the change, and a very brief summary of the changes.

There is a general blurb about what the report is for, who owns it, etc.

Next we have the generic selection criteria for a record to be included (in plain english), followed by a table breaking it down into each field the business wants included. the table has these columns:

Field Name (as they want displayed on the report - completed by the business)

Business Logic (plain english description of what it displays - completed by the business)

Calculation (SQL snippet, calculation, etc completed by IT to show how we will get the value)

Data Source (database or other source the data comes from)

seems to work pretty well!