Re: User's guide for Web applications

[Christine -dot- Anameier -at- seagate -dot- com]

Laura Varteressian asked about documenting web applications.

I'm just finishing up work on a training manual for an internal web
application, and we know that it's used as a de facto user guide, in the
absence of other user documentation. (Not ideal, but we don't have a lot of
options, seeing as I'm leaving in a few days.) The manual is a PDF file
that's meant to be printed, although if someone really wants to read a
200-page book online, we won't stop them. :)

To answer a few of those questions:  we opted for a step-by-step approach,
partly because it's a training manual, but partly because that's what the
users wanted. There's some overview material in there as well, but I'd say
at least half the manual is composed of procedures.

And I used plenty of screenshots, almost all of them cropped, many of them
annotated with callouts. Many of the steps in the procedures are
accompanied by a screen capture of the relevant part of the window. I opted
for this approach partly because many of our readers in Asia speak English
as a second language and I wanted to minimize the chances that anything
could be misunderstood.  The other reason for this approach: I believe it's
easier for the users. The images help clarify any aspects of the text that
aren't immediately obvious, and this way the users don't have do so as much
mental translation between the words on the page and the icons and fields
on the screen ("let's see, where is the Widget drop-down list... and is
that little flying-pig thing the Ferble toolbar button or the Gronkle
toolbar button?").

Keeping the manual up-to-date will be a challenge, especially considering
I'm the only tech writer on the project and I'm leaving Friday. The
graphics-heavy nature of the manual will make it trickier to maintain,
admittedly. Two external web sites we cover in the manual changed suddenly
and without notice; I spent a couple of days overhauling those sections of
the manual and updating the screen captures.

User feedback so far has been very positive.

HTH,
Christine
(soon to be c_anameier -at- yahoo.com)


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

*** 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.