Re: paperless docs, minimal manuals

[Rose Wilcox <RWILC -at- FAST -dot- DOT -dot- STATE -dot- AZ -dot- US>]

Robert Plamondon writes:

>It still stinks.  WinHelp is a "toy" application, inadequate for serious
>work, and companies around the world have decided to embrace it as
>the be-all, end-all documentation solution.  If you have an index,
>you get keywords for free, because they're right there in the top-level
>index entries.  If you just have keywords, you're hosed.

Woah! Robert, get down, my brutha!  Well, I don't agree with you about
Winhelp...  Ha!  When PageMaker came out a long, long time ago and Ventura
was just 1.0 and there was no FrameMaker.... I wrote a paper called,
"Desktop Publishing: A Tool or a Toy?"  Anyway, the on-line situation now is
*much* better than the desktop pub situation was then and is growing by
leaps and bounds.

A good writer can make up for the lack of keywords by astute naming such as
Bonnie noted in her earlier post.  I think you've only *used* Winhelp, not
written it.  I think that if you had a chance to write it, you could use
your negative experiences with bad help systems to guide you in creating
better ones.

>Not only that, but most Windows applications have a very short keyword
>list.  Annoying.  Unprofessional.

Yes.  Well, I'll admit I sent the first rollout of my products out without
fixing up my keyword lists, but I made it high priority for second rollout.
 I agree it's unprofessional, but don't blame the tool for the short keyword
lists.  It's either the writer's fault for dropping the ball on that task,
or management's :-), for not allowing the writer time to create it.

[snip]
>Additionally, you could print out the whole manual (or a subset) with
>a single operation -- something that is typically verboten with WinHelp.

Nein.  Not using Winhelp Office from Blue Sky.  There are probably other
utilities around that do that with Window 3.x help too.  The fault lies in
the company that did not develop the .dll, obtain the utility, etc. to add
that feature in.  It's not "verboten", just extra development work.

>Given that my best experiences with on-line help have been with manuals
>that have not been restructured AT ALL, I'm wondering what's so all-fired
>wonderful about restructuring manuals for on-line use?

Don't restructure a manual!  Write real help! Real helpful help!  You just
haven't seen the good stuff yet, Robert.  Hey, maybe someday soon, you'll be
*creating* the good stuff.  The advantage is "context-sensitive" help.
  Context-sensitive help  isn't always helpful for learning the product, but
if that's a need, provide hard-copy or on-line tutorials.  Where
context-sensitive help is wonderful is when I, the user, am on a window and
I can't figure out what to do, how to do it, or what the Gibbelty-gop field
is.  It turns me into an instant "power user" -- if the writer wrote
"helpful help".

>It can't be to
>make them smaller, since space on a CD-ROM is free.  It can't be to make
>them easier to use, since, in my experience, it makes them harder to use.

Yeah, I agree.  Don't do that to a nice manual.  Write the help from
scratch, using the manual as your reference (if you don't yet know the
product) as you go along.  Either that, or keep the manual an on-line manual
as you suggest.

>Is it simply that people are spending so much time working with a
>third-rate product like WinHelp, that they've taken their eye off the
>ball?

It ain't the product!

Winhelp is still a toddler....  And we as writers, are still learning how to
write usable help systems.  BTW, what is a second-rate help product?  I
think I know what a first-rate one looks like, but I would call WinHelp
second-rate instead of third rate... ;-)

Interleaf sounds good for the "on-line manual" type of document, but not for
context-sensitive on-line help systems.   I heard tell you can do stuff like
that with Frame, too... but I haven't tried it yet.

>Has anyone seen Windows 95 help?  The people at Microsoft are slow
>learners, but I'm wondering if they're started to figure out some of
>the basics.

The biggest change I've seen so far is the nifty tabbed contents page
deal....  But I haven't really gotten into it myself.  But since you are
working from an "on-line manual" paradigm, rather than an "on-line help
system" paradigm, the nifty tabbed contents page probably won't tickle
you....  However, Winhelp Office from Blue Sky with accompanies the lovely
and talented RoboHelp 3.0, contains many utilities that might interest you,
including FULL TEXT SEARCH (yowsa!) and a utility that displays all the
topics in a tree format, allowing you to print out ALL or PART of the help
file (yummy!)

I hope you run into some better-written .hlp files in the future, Robert.  I
hope I'm writin' some of 'em, too! :-)

Rosie A. Wilcox
rwilc -at- fast -dot- dot -dot- state -dot- az -dot- us
ncrowe -at- primenet -dot- com
"Art is always the replacement of indifference by attention."
Guy Davenport