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: User's guide for Web applications From:"Swallow, William" <WSwallow -at- courion -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Mon, 27 Aug 2001 17:36:31 -0400
>>>Do any of you write for a Web-based application?
Used to. ;)
>>>The technical writers here have been asked to create a user's guide in
PDF
>>>to be distributed to the end users of a new Web app.
Make sure it's not too big. Download time is an issue.
>>>We expect users to
>>>download the PDF from the Web site and search (and perhaps print) the
>>>document for answers to their questions.
Search will not work if the PDF is viewed via the web - only Find. Or is
that what you meant?
>>>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.
Pity. ;)
>>>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. (In fact, I even question the need for one, but that's a fight I'm
not
>>>going to win.)
You won't win it with me either. *vbg*
>>>How much information did you include in the application itself and in the
>>>user's guide?
Application gave "hints", help gave task-oriented info and "what's this"
info, and manual gave the brain dump.
>>>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?
Yes, info was repeated. Not everyone hunts for info the same way.
>>>What level of detail did you go to in the user's guide?
As deep as we needed to go. Our audience was made up of "admins" (I use the
term very loosely), so we needed to cover EVERYTHING.
>>>We're thinking that
>>>our users require a broad overview of the application, but not
step-by-step,
>>>"click here," "type your name" details.
Reasoning? What harm would including "how-to" info cause?
>>>How often do you update the PDF?
As often as the application changes (and as often as you can incorporate the
changes in the manual).
>>>Do you inform users of changes to the
>>>user's guide, and if so, how?
Yes. We had "updated" indicators next to the links to the PDFs.
>>>Do you include screenshots of actual Web pages in the user's guide? If
so,
>>>do you encounter difficulties in keeping the PDF current?
Yes, and no more difficult than any other technical document with screen
captures.
>>>Have you gotten any user feedback about the user's guide that you've
found
>>>helpful?
Yes. Every client I heard from absolutely loved having documents they could
print and read off-line. They also loved the fact that all application info
was available via the PDF documentation.
FWIW, we supplied multiple PDFs, broken up by task/application "section".
This was done for 2 main reasons:
1. Ease of download.
2. Ease of update - users didn't have to download and/or print the whole
manual if only a certain section was updated. We could just roll out the new
sections as needed.
*****************
BILL SWALLOW
Technical Writer
C O U R I O N C O R P O R A T I O N
1881 Worcester Road
Framingham, Mass. 01701
T E L * 508-879-8400 x316
F A X * 508-879-8500
www.courion.com
*****************
THIS EMAIL CONTAINS CONFIDENTIAL INFORMATION
MEANT FOR THE INTENDED RECIPIENT ONLY. PLEASE
DELETE THIS IF YOU HAVE RECEIVED IT IN ERROR.
*** 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.
