Documenting Reports 1

[tseh]

I have created several reports that my staff may modify for end-users. How can we document the report for reference for future developers?

 

[Ngolem]

I do it in a supressed "readme" formula that I put out of the way in a footer...I color it red so I can find it easily

BTW to make sure the forumla stays colored use a conditional suppress of 1 = 1. This is always true of course, but Crystal doesn't know that til the report is run...so it doesn't suppress the color in the design

 

[BFAGG]

Try exporting the report, selecting 'Report Definition' as the file type. This creates a text file containing all formulae, groups etc.

You can then edit the file, adding explanations etc;

You can also put comment lines in the selection criteria / formulae within the report by starting each comment line with //. This turns the text a green colour. Green text is ignored when the formula is processed.

 

[chelseatech]

I know we are not supposed to do any product promotion on these forums. Can I mention a great third party report documentation tool I've been using?

 

[rcman]

If you want documentation on what the report does (including listing all your formulas), you can use the export report definitions which is part of Crystal.

If you want something more polished including a 'picture' of the report layout, check out Report Miner.

Works for me!

 

[smcnulty2000]

This all depends on how much effort you want to put into this and whether you believe the next person will read it (and whether someone is paying for the documentation time). I hand document.

When documenting reports I use a variety of tools; a flowchart program for the table relations, comments inside the report, a PDF maker or equivalent to increase my publishing flexibility and a word processor.

I find the elements most critical to the process to include pretty much on a per-report basis; a db list, tables, a link diagram to show relations, the selection criteria, explanatory notes in any formulas through comment lines, a naming convention that remains consistent at least throughout the project, and notation on grouping.

I also try to find a way to leave explanatory notes around for any unusual choices that were made. If possible, notes as to what was asked for and what was delivered. Notes on particular permissions that had to be obtained to make a report work. Things like that.

If any db investigation was required to make the reports, those docs become part of the effort.

I don't feel that field lists are necessary, nor do I feel that I need formatting or layout information. These are irrelevant. I'd rather know why a statistical formula derives from a column B instead of column A than to know that it happens to be Magenta. Or even why it happens to be Magenta.

Any of these things being present when I walk into a project is an unexpected bonus, so even if you don't go whole-hog any of these can help the next developer. And cut the costs to everyone involved by not making the organization relearn the lessons that were learned.

And of course it helps to have them in an organized file structure on a network or in a binder. TOC if you have time.

All of this developed around the fact that I have a tendency to forget things myself, so when returning to a report I would become unhappy with having to relearn any piece of it.

 

[smcnulty2000]

Addendum: After posting this, I had a client give me a reason to create a field list.

Their programmers are going to start changing the underlying fields. When they change them, they won't delete the old fields, they'll just stop using them.

What we've convinced them to do is to email us with information when they are going to stop using a field in exchange for a new field.

And what we're going to do is to build a unified field list that will track which reports use which fields, so we can do a quick find in the doc to locate all reports that need a particular change.

Since the report list is fairly long this will be a necessity.

[sigh]