User's guide for Web applications?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Laura Varteressian reports: <<[We] have been asked to create a user's guide
in PDF to be distributed to the end users of a new Web app. We expect users
to download the PDF from the Web site and search (and perhaps print) the
document for answers to their questions. There is no plan for online help
for the application, so all users questions need to be answered within the
application itself or in the PDF. >>

Think of how your audience will look at this situation: If they're using a
Web application, it's quite likely that a high proportion will be using the
application from a laptop or a library computer, or in a situation where you
can't guarantee that they have a printer handy. (In a large corporation, not
everyone may have access to the PDF or the right to print it.) Moreover, I
don't know about you, but it pisses me off mightily to spend a few hundred
bucks on software and then have to print my own manual--single-sided,
low-resolution, wasting much of the page, at several times the cost of a
professionally printed manual, etc., all of which just add insult to injury.
That being the case, PDF isn't a particularly good choice. If you're stuck
with a PDF solution, at least make an effort to format the PDF for onscreen
use rather than forcing users to print it out, and consider producing two
versions: one for printing, and one for online reading. (If you pick a
simple, clear layout, sometimes all you need to do is adjust the page size
and let the text reflow. Sometimes it's a bit more complicated.) Better
still, since it's a Web-based application, spend some time making the
application itself as usable as possible via affordances (onscreen
explanations, good labeling, etc.) to minimize the need to resort to online
or printed help; then, provide the help directly from within the application
by integrating it with the tasks and making sure that each screen has online
help via a single mouse click. While you can certainly create something
professional with a proper authoring tool, you can also go the simple route
and simply link to a page of onscreen help from each screen in the
application.

<<Although we have extensive experience creating user's guides for
Windows-based apps, we're new to creating a similar document for a Web-based
app.>>

Spend some time thinking about what will be different for your audience: Can
they cut and paste and undo like they do in Windows and the Mac? Do they
have the same File Save dialog boxes? Where will their data be stored and
how will it be backed up? Are there access restrictions or password
administrivia to deal with? These and other issues are all things you'll
have to explain to users.

<<How much information did you include in the application itself and in the
user's guide? Did you find that some information had to be repeated in both
media or were you able to make a clear distinction as to what goes in the
app and what goes in the doc?>>

This depends entirely on the application and the user, but in general,
you'll see considerable overlap, with the main difference being that the
online version should be more concise. Where you can't guarantee that users
will have access to the printed or online manuals, it's particularly true
that you need some redundancy.

<<What level of detail did you go to in the user's guide?>>

"As much as necessary, and no more." Minimalism works in any situation,
provided you don't interpret minimalism as "the least text I can create
without getting death threats from my audience".

<<We're thinking that our users require a broad overview of the application,
but not step-by-step, "click here," "type your name" details.>>

What are _your users_ thinking? <g> Sorry to sound facetious, but if you
understand their needs, that--and not my opinion or yours--will give you
your answer.

<<How often do you update the PDF?>>

As often as necessary. The problem with updating a PDF rather than online
help is that users never know that something has changed and that you can't
easily integrate it with the application to produce context-sensitive help.
With context-sensitive help, they'll see the new information as soon as they
open the help file for a given topic. With PDF, you have to alert them to
changes, and if they're like most of us, and don't read change notes, you'll
be failing to provide adequate notification. Worst-case scenario: I'm voting
with my wallet, and every month, I have to print out your new manual at my
expense, you can bet I'm not going to be happy. If a change has important
consequences, information on the change _must_ be integrated with the task
where it becomes part of the work, not hidden away in a manual somewhere
where it will be missed.

<<Do you include screenshots of actual Web pages in the user's guide?>>

Use screenshots where necessary to explain something that's best explained
with "look here" rather than several hundred words of description (e.g.,
"the third widget under the second heading of the fifth tab of the dialog
box; it's the widget that looks kinda like a squished bug, not the one that
looks like an octopus").

<<do you encounter difficulties in keeping the PDF current?>>

You shouldn't have any more difficulty than you did inserting current
screenshots or text corrections in the original version. Create a layout
that's flexible enough to handle ongoing changes (e.g., start new chapters
on a new page so text in one chapter can reflow without affecting pages
breaks in the next chapter), then all you need to do is regenerate the PDF
after you update it.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

A landmark hotel, one of America's most beautiful cities, and 
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.