Re: What would be the best approach?

[Ben Kovitz <apteryx -at- CHISP -dot- NET>]

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
> repetitious.
>
> 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
the software:

   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
   sales report.

   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
   operators.)

   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.

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Author,  _Practical Software Requirements: A Manual of Content & Style_
http://www.amazon.com/exec/obidos/ASIN/1884777597
http://www.manning.com/Kovitz


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=