TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: What would be the best approach? From:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Sat, 6 Feb 1999 13:23:07 -0700
Suzette Seveny wrote:
> I'm sitting here (lone tech writer) trying to decide on the best
> way to approach a user manual for a new software application,
> when the though suddenly struck me - I'll ask the experts! Maybe
> one of you has been faced with a similar dilemma, and can share
> your thoughts with me.
> The application is a browser-based ad hoc reporting system.
> There are no canned reports available at the current time, but
> may be in a future build.
> Some background - this is a retail organization, and the
> application will be used both at head office and at the stores.
> Users can select the criteria they want in the report (for
> example, number of stock items vs. value of stock items, for an
> individual store vs. all stores vs. range of stores, etc.)
> Should I approach this in a linear fashion? Just going through
> the application, showing users how to select different values and
> explaining what those values mean? Or should I break it down
> into every possible variation of a report? For example, one
> report might be How many gift certificates were sold by store
> within a time span, another - How many gift certificates were
> redeemed by store within a time span, How many discounted sales
> took place within a time span, How many times and for how long an
> employee opened the cash drawer within a given date range, etc.
> The list would be extremely lengthy and would be very
> I tend to always like to approach a project from a User Task
> perspective, but with an ad hoc reporting system, I suspect this
> might not be the best method. Any thoughts?
I completely agree that this is not a place to apply the
task-oriented approach, at least not in the usual simple way.
The reason for the mismatch is that the user has to be able to
creatively invent new tasks and new uses for the program feature.
The task-oriented approach is only for features where the user is
to be directed down a narrow path, like cattle being driven to
pasture, or where the user knows in advance what he wants the
software to accomplish. This situation calls for teaching the
user the properties of the tool, so the user can invent his own
ways to use the tool. However, you can still connect it to tasks
in a useful way.
Here's how I might go about documenting it. I'm sure you can
come up with improvements, especially since you know more about
Briefly explain that the such-and-such part of the program
lets you generate reports, and that you can define a report
once and then print from it over and over, like a month-end
Show a *realistic* (but simple) sample report, with callouts
pointing to the parts of the report that correspond to
information that the user has to enter in the browser to
define the report.
Explain what each of the relevant concepts is: fields,
formats, grouping, layout types, sort order, filtering
criteria, and Boolean conditions. Ideally, each of these is
illustrated with some teeny-tiny but realistic example.
In a table, list all of the fields to select from: how each
field appears in the field list, plus an explanation of what
each one means, if it isn't self-explanatory. A similar table
should list all the field formats, with comparable (and
realistic) examples of data in different formats. If there
are, say, three report layouts to choose from, then show each
of these in a graphic. Each report should contain the same
(realistic) information, and the reports should all fit on one
page (or two-page spread).
Show the screen where the user enters all this information
into the browser, with callouts that correspond as simply as
possible to the callouts on the report.
Have a generic step-by-step procedure for defining a report,
following roughly this two-level organization:
> To define a report:
1. Go to the report generator: Click such-and-such button
or point your browser to such-and-such URL.
2. Select a layout: click <whatever>.
To change the layout later on, click <whatever> again.
3. Select fields: click <whatever> to select the field, and
click <whatever> to select its format.
To change where a field appears in the report, drag
<whatever> to <whatever>.
To remove a field, click <whatever>.
4. Select a sort order: click <whatever>.
The fields in the sort order need not be fields that appear
in the report. For example, you can sort an employee
report by date hired even if date hired is not one of the
columns in the report. <You might explain this in the
introduction instead of in the procedure.>
To change the sort order, click <whatever>.
5. Select filtering criteria: click <whatever>.
The fields that define the filtering criteria need not be
fields that appear in the report. <etc.>
To change the filtering criteria, <whatever>.
6. Click "Save" to save the report.
Such-and-such window appears. <small screen shot>
7. Choose a name for the report and type it in <whatever>.
8. Click OK.
You might have to break some of my "click <whatever>"s into
little series of sub-steps. I'd work hard to avoid moving
these little sub-series into separate topics, because that
makes the process look more complicated than it is. In fact,
I'd try to make this whole procedure fit on one page. (Of
course, the UI is bad and the process is horrendously
complicated, then it might be better to separate them, to make
the process seem as complicated as it is.)
Have a step-by-step procedure for printing or viewing a report.
Have a step-by-step procedure for renaming a report.
Have a step-by-step procedure for deleting a report. (You
might be able to combine these last two in some clever way.)
And now, the fun part: show a few sample reports and how to
define them, if there's anything tricky about them. Focus on
two types of reports: the most common reports, and reports
that are useful to end users but that they are unlikely to
think of themselves. For example, you say, "The following is
a useful report to run at the end of each month:" or "A sales
staff is often particularly interested to learn the
information in this report:"
Naturally, you might want to reorder or change the grouping
above. But there are a few key points:
Showing the finished product first helps the reader understand
the purpose of everything that is to follow. Putting it last
would ask the reader to hold everything in mind at once while
waiting to see what the point of it is. (Perhaps the "mental
buffer overflow" problem isn't so critical in reports, where
most users are already familiar with what reports are and what
it takes to define them, but this can be a big problem with
other kinds of software.)
The introductory section gives the reader the conceptual
vocabulary to begin thinking about what sorts of reports he'd
like to print. This is very important, and frequently omitted
in purely task-oriented manuals. A task-oriented organization
gives answers to questions, but there is a kind of knowledge
that you need before you can ask a question. A reader can't
think, "How do I define filtering criteria?" if the reader
has never heard of filtering criteria. Patiently explaining
Boolean operators is especially important for some users.
(BTW, a really clever UI can often dispense with Boolean
The use of realistic data in every example, plus the sample
reports at the end (and how to define them), stimulates the
reader's imagination to come up with useful new kinds of
reports. This technique gets the reader's intelligence to
help make the software more useful. A purely task-oriented
organization, in many cases, has the opposite effect: it
says, "go down these paths when I tell you to, don't look
right or left, and don't ask any questions."
Giving the reader ideas for useful reports to create helps the
reader *run the business* as much as it helps him operate the
software. All user's manuals for business software should be
written with this perspective in mind: everything must serve
purposes *outside the software*, and the connection between
tasks, or software features, and benefits to the business
should generally be made very obvious. Too often, system
analysts, programmers, and yes, technical writers treat the
software as an end in itself, and users as existing only to
serve it, not the other way around.
Saying "To change..." in the main procedure encourages users
to experiment. Many users are intimidated by software and are
worried that if they go even slightly off the path, they'll
get into trouble. Saying "To change..." brings up the idea
of changing their mind, helping them relax a bit, since they
no longer feel like they have to get everything right the
first time. In more complicated software, you can also teach
this attitude in a tutorial, where you show the realistic
process by which someone creates a complex product, involving
plenty of exploration and backtracking.
Mentioning in the opening paragraph that "you can define a
report and print it many times later" slips in the
distinction between designing and running a report. I suppose
that today this isn't as much of a problem as in years past,
but many people find these intangible "things" that you
"create" or "define" and then "store" in the computer somewhat
strange. Depending on your audience, you might want to make
this concept even more explicit.