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.
We have just gone through a similar experience. I cannot point you to
any research on the wisdom of providing documentation exclusively online,
but I can give a few tips. Our company decided with rather short notice
to eliminate printed doc. We now only provide a printed installation
guide. The first version of our product to incorporate this approach is
now in LA, so we don't have a lot of user feedback yet, but we have
learned some lessons.
1. Because of the timeframe involved, we more or less dumped all of our
printed doc into online help files without much planning. By all means,
take the time to select a layout and presentation that fits the material
you are presenting. Also consider if the structure of your information
is logical once it's placed online. Portions of our product are very
complex and descriptions span many pages in a doc. Online, the
information seems to scroll forever and will likely lose some readers.
In addition, consider shortening your procedural descriptions. Instead
of, "From the File menu, choose Open. The Open dialog box appears.
Select the file you wish to open etc., etc." simply say "Open Myfile."
I think that for most basic desktop operations users don't need the
additional instruction. However, for more complex tasks they might.
2. Think long term. Anticipate how users will locate the information
they need, how it will be indexed or searched and which platforms they'll
be using. Our customers are primarily Win 3.x based. However, Win 3.x
help files do not easily support the more advanced search features of Win
95 help. This meant we spent a lot of time programming macros instead of
writing help (Yes, I know RoboHELP and the like do it for you, but we
didn't have the luxury of such utilities and had to build our files from
scratch. If you can swing such a utility, it'll save you lots of time
and frustration). Also, will you need to translate the document? If so,
are your translators equipped and trained to build online help files?
3. What about bitmaps and images. They are expensive to translate, time
consuming to capture and increase the size of an online help file
dramatically. Plan whether the artwork in your documentation is critical
to include in an online document. We took most of ours out reasoning
that a user will have the application available next to the online help
file and that therefore the screen captures had little value add. There
is an argument to be made for confiming a user's actions through screen
4. Finally, read and edit your procedures carefully. What makes sense
in a printed doc can suddenly sound silly or be confusing in an online
help file. ("The diagram below," "In the previous section," "Go to page,"
Looking back, I think our online documentation turned out pretty good
considering how quickly it was developed. So far we have not heard any
overwhelmingly negative comments from our users. But as I mentioned,
we're only in LA. Looking ahead, our next challenge is to improve our
documentation by bringing it more closely in line with some of
Microsoft's suggested styles and to more closely coordinate and integrate
our individual files.
Sent: Thursday, July 25, 1996 12:12 PM
To: Multiple recipients of list TECHWR-L; RODR
Subject: Online vs. Hardcopy documetation
The company I work for is currently exploring the possibility of
of our hardcopy documentation with online manuals (we would still keep
installation, getting started, and troubleshooting information in a small
I was wondering if anybody has, or could point me in the direction of,
research about the pros and cons of doing this. I have a study from
I am looking for something more current.
Also, if you have already gone through a similar transition and have
interesting feedback, comments, suggestions, etc., I'd love to hear it.
(ellenh -at- cheyenne -dot- com)
TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send administrative commands
ALL other questions or problems concerning the list
should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-