Can you omit menu documentation for a GUI in WinHelp?

Subject: Can you omit menu documentation for a GUI in WinHelp?
From: Carl Stieren <carls -at- CYBERUS -dot- CA>
Date: Fri, 16 Apr 1999 08:59:58 -0400

Hello Friends:

A colleague of mine is documenting an particular sort of GUI - it's an
integrated development environment (IDE) for a programming language. It's
crucial that she help the user learn to operate this thing in a way that
will make life easier -- not more difficult.

Now an IDE is a bit different from a paint program or a word processor.
True, you can go in and mess around with an IDE with no plan or instruction,
but you won't get much out of it. You'll get a fraction of the use, or --
worse yet -- you'll fail and you'll say, "This thing is a bunch 'o crap!".

So here's her problem:

1) She's got to explain to the user the model of the IDE, including all the
necessary concepts, procedures, inputs and outputs.

2) She may want to present them in a sort of mini-tutorial.

3) She is limited to Windows online help as the required medium for this
documentation.

There's also a fourth problem ...

4) Someone on the project said, "Nah, don't document the menus and options!"
(that might encourage the user to experiment with no preparation: the use of
the menus and options should be explained only in context of a model or in
specific procedures).

So... what do you think?

I'd appreciate suggestions for my colleague's problems 1) to 3), but I'm
also concerned about No. 4 - leaving menu and option documentation per se
out of a WinHelp file.

Has anyone out there ever omitted traditional menu and option help from a
WinHelp file and got away with it?

- Carl Stieren
Ottawa, Canada
Carl Stieren .....................................email: carls -at- cyberus -dot- ca
Technical Writer and Designer......................deep in Silicon Tundra
Ottawa, Ontario, CANADA.........................1 hr 40 min from Montreal
Carl's "Text and Subtext" Web Page..................www.cyberus.ca/~carls

From ??? -at- ??? Sun Jan 00 00:00:00 0000=




Previous by Author: ToC for "Table of Contents"?
Next by Author: Interview Questions
Previous by Thread: Re: Keeping it together
Next by Thread: Document the menus!


What this post helpful? Share it with friends and colleagues:


Sponsored Ads