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:Which came first: the manual or the online help? From:"Geoff Hart" <Geoff-h -at- mtl -dot- feric -dot- ca> To:TECHWR-L -at- lists -dot- raycomm -dot- com Date:Wed, 15 Sep 1999 09:19:05 -0400
Aoidìn Scully wondered <<When you're creating both a
manual and online help for an application, which do you
create first? I always thought it was easier to create a manual
and then base the online help on that...but others in my group
do it the other way round.>>
As always, it depends on the audience. Personally, I prefer
your approach, but for two good reasons: First, I think the
state of the art in online help is pitiful, and more attention
needs to be devoted to paper documentation until things
improve; when "online help" is no longer on the Letterman
top-10 list of oxymorons, I'll begin to change my tune.
Second, the software we've been developing has been
destined for an audience that originally had little computer
experience (this is changing fast). That being the case, we
needed to have something people could use to get them
started during the beta period, quickly enough that they could
start merrily crashing the software. Once the software became
stable enough for them to become familiar with it and thus for
them to consider using help files (and stable enough that we
actually knew where to link the help files), we shipped early
versions of the online help so those could be tested too.
Seems to have worked just fine!
If your company's goal is to minimize or even eliminate paper
documentation, then it makes a certain amount of sense to
start with the online version and then put on paper only what
you really need to put on paper (e.g., "what should I do if my
computer can't open the CD that contains the help file?"). I
don't much like this approach; I've been working with
computers for more than 20 years now <eek!>, but I still want
paper in my hands when I need to look something up.
Judging by the success of the "for Dummies" style of book, I
suspect I'm far from alone in this, and that companies who are
trying to eliminate paper docs are ignoring a potentially large
profit center. (My somewhat tongue-in-cheek article on this
very subject should be appearing in the "Witful thinking"
column in _Intercom_ towards the end of the year or early
"Perhaps there is something deep and profound behind all those sevens, something just calling out for us to discover it. But I suspect that it is only a pernicious, Pythagorean coincidence." George Miller, "The Magical Number Seven" (1956)