Re: a good manual

[Jane Bergen <janeber -at- CYBERRAMP -dot- NET>]

I look first at organization: does the topic arrangement make sense?
Is it easy for me to tell where the writer is taking me? Am I able to
figure out the organization without a "guide to the guide"?

Then navigation: Are the headings skimmable? Is the font readable? Are
the graphics clear and appropriate?

Then INDEX: if a book does not have an index (absolutely unacceptable
for any reference work), then it goes in the trash or in the far
recesses of my bookshelves. It's worthless.

Then writing style and content: Is the information there? (If it's not
in the index or the toc, I'm not about to play twenty guesses or do
hunting and pecking....my beef with the FrameMaker 5.5 manual.) Is it
clear and readable? (depending on how desperate I am, I look for
active voice, action verbs, good use of lists and tables?...again, if
the information is really, really good and accessible, I'm more
willing to forgive some things, unless I'm editing...then it's a
different story) Does the writer use standard terminology (is it a
"tab" or a "stop")?

I hope others answer this question, Drew. I think it will be
instructive, especially to new writers. Unfortunately, I don't find
many manuals that I really think are "great" -- some are good, many
are passable, and a very few are garbage.

My pet peeve is to find out that the program can do what I want, the
manual even explains and shows the dialog box to do it....but then
does not tell how to open the dialog box!!! And it's not always
intuitive as sometimes it's from a button on some other obscure dialog
box. Paint Shop Pro and Picture Publisher (at least a few versions
ago) were guilty of that. Seems to be a graphic thing, maybe.

Jane Bergen

> -----Original Message-----
>
> I guess working in the field has sharpened my appreciation of good
> technical documentation (that, plus the particularly
> labrynthine Unix man pages). Are there other
> favorites out there? What do you like most or
> least in the manuals you yourselves use?
>
> ////////////////////////////////
> Drew Krause           Miami, FL
>      dkrause -at- netside -dot- net
> \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\


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