RE: Question on documenting reports

Subject: RE: Question on documenting reports
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 29 Sep 2020 09:06:08 +0000 (UTC)

In terms of a "procedure", you have one which is "Printing/Running/Doing a Report." Then you have many different reports that serve different purposes. I would shudder to think you're contemplating a repeat of the Doing a Report for every report type.
It's very important that customers know what the different report types are, what they're good for, and any caveats or special things to know for each. It sounds like that's what you're doing when you document each report in order. You can have a link to the Doing a Report procedure in each.

If you feel the need for a gerund-based list of the reports, by all means provide it. But I would also use links from that. Getting a List of All Charges -- See List of Charges report. You could have a section in your reports overview that offers this list. If one report type has many gerund-based uses in it, then put that shorter list in the report description.Â

IMO, excess duplication is as confusing and frustrating as no procedures... If not more so. There are limits to the gerund-based list. If you see a list with many repeats of the same gerund (in this case, "getting a list of"), then perhaps the value of the list is suspect. Would I have a TOC with 20 or more entries that all start with "Getting a list of..."? No I would not.


From: Joe Weinmunson

The software I document currently has a Reports section in the Help file.
It goes through each report in the same order they appear in the menu,
explaining both why you would run such a report and the options available.
However, I am wondering if I should expand or replace this with more
task-based topics. A few reports are particularly versatile and get run all
the time for very different reasons. Example: instead of a single topic
about the Posting Report should I add topics like:
* getting a list of all payments made in a quarter;
* getting a list of all charges made by a given user;
* getting a list of all charges made for residential service.

How have others solved this dilemma?

Joe Weinmunson

?What you read when you don?t have to determines what you will be when you
can?t help it.?
--Oscar Wilde

Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Previous by Author: Re: Need help with Acrobat in-line editing
Next by Author: Usage of chemistry abbreviation for Normal (N)
Previous by Thread: RE: Question on documenting reports
Next by Thread: A governmental blunder that probably won't hurt us. Much.

What this post helpful? Share it with friends and colleagues:

Sponsored Ads