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:Building help systems for ASP products From:"Rowena Hart" <rowena -at- vocalscape -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Tue, 6 Mar 2001 11:38:00 -0800
Thanks to all of the people who contacted me
offline to discuss the issues surrounding how
you create, implement, and maintain a help
system that is embedded into the UI of an
HTML-based ASP product UI (rather than creating
a stand-alone help system "outside" of the
product). Some of you requested that I post
a summary to the list. For those who asked,
here you go...
People who are interested in embedding help
in an application will want to consult the
following Web resource:
<snip>
Cheryl Lockett Zubak has some information on embedded
help on her site
(www.workwrite.com) including some references on how to
create (don't know
if there is any usability studies in those refs).
</snip>
>From this site, you can access the "Help
Matters Webzine", which leads to a great
article that describes embedded help. This
article offers links to several other
published articles on embedded help,
including some valuable articles written
by usability experts.
The biggest issue with embedding help seems to
be maintenance. As you can imagine, if the
help is actually a part of the UI you can
expect to face some serious maintainability
issues. One person I talked to had a very
interesting XML-to-HTML solution:
<snip>
First, we write all of the help topics in a single XML
file (with
corresponding DTD and XSL style sheet). Then we parse
the XML into a single
HTML file with several special non-HTML tags. Finally,
we use a Perl script
to splice up the HTML file into individual topics
(using the non-HTML tags
to indicate where to cut the file up). The resulting
files' names correspond
to the components or pages they are describing.
Once we have all of the little HTML files, we copy them
into the Java
application's source tree, and with a little luck and a
lot of testing and
verification, voila! -- a help system is born!
An added coolness factor to this approach is apparent
when the application
and help need to be localized. Instead of having to
translate scores of
little HTML files, the translators only have to work
with single XML files
(just like the tech writers). We then use the same
parsing and splicing
process to create the individual help topics.
</snip>
Usability issues for embedded help include
(a) users who think that pop-up help or
help panes are a bug in the product,
(b) power users who do not want to see
pop-up help whenever they mouseover a button
or field, (c) user desire to 'turn off' help
functionality built into the UI.
Usability benefits are that (a) users receive
several levels of help, (b) embedded help
does not look like help, rather it looks like
a feature/function of the product, (c) embedded
help answers questions before users need to
ask them, and in this way is extremely
preventative.
Once again, thanks to everyone who responded
(there were quite a few!). It seems that more
and more people are building embedded help
into their products. I won't be surprised if
there are an increasing number of threads on
this topic in the next year.
Cheers,
Rowena
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Rowena Hart
Senior Technical Writer
Yahoo! Messenger ID rowena_hart
VOCALSCAPE Communications Inc.
Unit 203 - 3991 Henning Drive
Burnaby, BC Canada V5C 6N5
Tel:(604) 437-VOIP (8647)
Fax:(604) 437-8646 http://www.vocalscape.com
"The Future is Hear.com"
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
IPCC 01, the IEEE International Professional Communication Conference,
October 24-27, 2001 at historic La Fonda in Santa Fe, New Mexico, USA.
CALL FOR PAPERS OPEN UNTIL MARCH 15. 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.
