Re: Structuring online help/documentation

["Susan W. Gallagher" <sgallagher -at- STARBASECORP -dot- COM>]

Glenda Jeffrey writes...

> Can I open the can? ;-)

[snip]

> Our software can be divided into "modules", and I'm writing a manual
> on each module. The manuals are structured like this:

>    1) What is this module? When should I use it?
>    2) Short tutorial for those too impatient to read the whole manual
>    3) Basic concepts the user needs to understand in order to make sense of
>       the reference material
>    4) Reference material

> The first three sections are meant to be read by someone new to the
> software. They're not reference material -- they should be read more
> or less cover-to-cover. The fourth section is meant to be context
> sensitive. That is, it's a task oriented description of how to use
> each icon in the GUI; for example, "How to do xyz using the abc icon".

I first have to argue with your basic premise for the first three
sections. Preparing information that you assume will be read "cover-
to-cover" is presumptious enough in a paper book. Online -- ain't
nevah gonna happen! Presenting conceptual information online isn't
easy but you can do it. Just be sure that each topic can stand
independently and that you are concise. Follow the "rule" of only
answering one question per topic and you'll be ok. And, of course,
provide hyperlinks to related information.

You didn't mention the platform or software you're using, so I'll
have to be general here... Usually, context sensitive help refers
to the kind of information that describes the control elements of
the screen and the kind of data they require (e.g., the description
can contain any alphanumeric characters, spaces included, up to
256 characters in length).

What you're calling reference, you're describing as procedural
information -- how do I do it. I've seen this type of information
offered as "context sensitive" help before, and you can get away
with it as long as you can segregate the help and the portion of
the program in which the procedure is performed. If a procedure
spans more than one or two screens, you'll run into problems as
to where you attach the procedure -- what if the user accesses
help on screen 3 and the topic starts by describing screen 1????



> Section 4 would be heavily hyperlinked to section 3, so that users
> too impatient to read the "basic concepts" section can easily refer
> to it when they run into things they don't understand in the reference
> material.

> I'd like to issue all these manuals both in print and as online books.
> The context senstivity software would then hyperlink into the right
> place in Section 4, and would present the user with ONLY the section
> of current interest. The user is free to push a button that brings
> up the entire book, opened to the right "page", for further reading.

> Does this approach make sense? How have you folks tackled this problem?

You don't say how you'll be formatting the "tutorial" section.
How will you keep the user from confusing the "tutorial" help and
the procedural help?

Although the organization you propose sounds OK for a help file/
online doc, is it the most effective organization for paper?
might you not be better off comingling your sections in the paper
book? (e.g. Task 1 --description, concept, procedure; Task 2 --
description, concept, procedure...) Consider that the tutorial
may be more effective on paper if you present it separately --
either as its own chapter or as its own pamphlet-sized volume.

I've never been a big fan of single-sourcing docs (and I've
often taken the time to make that perfectly clear on this list ;-)  )
I'm not saying it can't be done, but it takes real work. How will
you write? Will you use the concise no-flourishes approach that's
appreciated online, or will you embelish as if you were heading
directly to paper?

Just a few thoughts. I'll shut up now %-)

Sue Gallagher
StarBase Corp, Irvine CA
sgallagher -at- starbasecorp -dot- com