Re: document structure? minimalist docs?

["Hutchings, Christa" <cwhutchings -at- HOMEWIRELESS -dot- COM>]

Rebecca -
Although most of my TW career has been in the
computer/telecommunications arena, I did spend 15 months recently at a
company that manufactured industrial equipment. The manuals there were
organized as follows:
1 - Safety
2 - Description
3 - Installation
4 - Operation
5 - Controls
6 - Hydraulics
7 - Maintenance
8 - Options

These manuals ranged in size from maybe 50 - 300 pages. The Safety
section was pretty much boilerplate, with the same info being used in
every manual for every product line (our legal department dictated that
the Safety section be first). All other sections pertained to the
equipment being documented. The Description section contained a general
description of the equipment, what it did, etc. It also contained all
specs for the equipment. Installation was exactly that - info on
installing the system on the plant floor. Operation was detailed info on
operating the equipment. (We also produced a stand-alone Operator's Card
with brief operating instructions that was attached to the machine
itself.) The Control section contained info on the electronic controls
that operated the unit - how to troubleshoot and change out boards, etc.
The Hydraulics section contained info on the equipment's pump and
manifold, the Maintenance section described daily and monthly
maintenance procedures, and the Options section contained info on
optional add-on boards, etc.

Unless there are specific reasons why you want a stand-alone
Installation guide, I'd consider keeping that section as part of the
main manual, for the simple reason that it gives you one less piece of
documentation to keep track of. Why give yourself an extra manual to
worry about, unless it is really needed? However, if your manuals are
frequently carried out to the machine, and leaving the installation info
in the manual makes them so large that they are hard to carry around,
that might be a good reason to move that section to a stand-alone
manual.

And by all means, get detailed info on checking and changing the oil
into the manuals! Don't fall for the line that "the customer will know
what to do" - that leaves the door wide open for legal action against
the company when some newbie blows the machine up because he didn't have
the correct info for maintaining the equipment.

Also, you are right, there has been a big push for minimalist
documentation lately. This does not mean however that you leave out
important information. If your equipment could injure or kill someone if
not used properly, it is extremely important that your manuals be
complete (without being redundant or overly detailed). Tell your users
what they need to know to install, operate, and maintain the equipment
SAFELY and no more (don't give them Theory of Operations, etc). It's one
thing to get minimalist when documenting a SW app and something else
entirely to do it with a large piece of industrial machinery that could
maim or kill someone. Don't let yourself get pressured to cut the size
of the manuals if it means leaving out vital information. For instance,
the manuals at my previous company contained a lot of detailed info on
various procedures because the equipment operated under high pressure
and at high voltage and operators or maintenance personnel could be
seriously injured if they didn't follow procedures correctly. Despite
this, just before I left, we received a directive from a company VP that
we were to cut the size of all our manuals by 50% - no arguments, just
do it. On my last day there, they were still trying to decide what info
to leave out without jeopardizing the safety of the operators or
maintenance people.

Hope this helps. Feel free to contact me directly if you need further
info.

Chris Welch-Hutchings
Senior Technical Writer
Home Wireless Networks, Inc.
mailto:cwhutchings -at- homewireless -dot- com




-----Original Message-----
From: Rebecca Price [mailto:beccap -at- RUST -dot- NET]
Sent: Monday, July 06, 1998 6:48 PM
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Subject: document structure? minimalist docs?


As I've said, I've inherited a tech comm department (of 1 person - me)
that has gone... shall we say fallow?... for the last several years,
and consequently is a mess.  We build heavy machinery.  our manuals
are maybe 100 pages long, if that.  (I suspect the brevity is because
we're not adequately documenting things, but that's another question).

The previous person who did our documents put the manual in the
following order, on the grounds that things used most often should be
up front in the document: safety notice, reference section, user's
guide, installation.  Although I agree that the reference section will
be used most, the order seems odd.  any advice? I've been away from
documenting actual machines (as opposed to software) that my awarness
of issues in this area is a tidge rusty.

I've started to create a separate installation guide (it's pretty
standard for all our machines).  There used to be one, many moons ago,
but it has fallen into disuse in favor of a specific chapter in the
book.  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...

also, I know that the trend lately has been toward minimalist
documentation... does this apply to heavy machinery too, or just to
software? 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?

TIA -- and thanks, guys, for helping me so much with this new job.  I
*like* documenting machines, but it's been over 15 years since I last
did much.

-Becca

--
Becca Price
beccap -at- rust -dot- net

"Wisdom begins when you discover the difference between 'That doesn't
make sense' and "I don't understand.' "

Children of God, by Mary Doria Russell; pg 142-143


~~~