Re: document structure? minimalist docs?

[Barb Philbrick <caslonsvcs -at- IBM -dot- NET>]

Becca:

In most cases, I use the same outline Chris does. For one of my
clients, we broke hardware (primarily installation and specification
information) and software (how to use the keypad and program the
device) into two separate books.

>Has anyone arguments in favor of a separate document as opposed
>to a specific chapter in one big book?  these things are installed
>*once* and not moved casually...

I like having installation information somewhere easy to get to. When
someone gets a new widget, they want to know right away how to install
it and make sure it works. I think separate books for normal operation
and installation are an excellent way to address the problem. It does
add some cost to the books, however, so some people in your firm might
dislike it.

At my last client's, just before they had a "no contractors" edict, we
had started creating a bare bones installation for motor drives. In
discussions on another document, we discovered that what customers
really wanted was a quick and dirty installation to check the
equipment. In addition, the quickie installation was all some
customers needed. Unfortunately, the axe fell before I got to finish
the project, so I can't tell you how the reception of it was. 

>also, I know that the trend lately has been toward minimalist
>documentation... does this apply to heavy machinery too, or just to
>software?
To some degree, it applies to all documents. For example, if you are
writing to "qualified electrical personnel," you shouldn't have to
tell them what NEC is or that they need to follow it.

I've seen some awful use of minimalism lately, however. It's
incredibly frustrating to have a complex question and be blown off in
the documentation.

> How does one do "minimalist" documentation for machines? I
>know that our current documents are inadequate (for example, our
>maintenance section says to check the oil every 6 months, but doesn't
>say where, what to look for, or how to add new oil... or what kind to
>add even.  when I asked, I was told "they'll know, and they'll use
>what's on the floor anyway." - erk.) but how much is too much?
If your audience is experienced machine builders or users, I'd tell
them where to check, how often to check (hours of use is probably more
relevant than months), what oil to use (especially if the warranty is
affected if they use the wrong grade), and where the drain is if they
need to change the oil, if applicable. I wouldn't tell them how to
read a dipstick or how to tell if the oil need changed.

My view of minimalism is that you tell the reader what they need to
know and no more, and then get out of the way. The tough part is
determining what your reader needs to know.

Hope this helps --

Barb

Barbara Philbrick, Caslon Services Inc.
Technical Writing. caslonsvcs -at- ibm -dot- net
Cleveland, OH