Heavy metal manuals

["Geoff Hart (by way of \"Eric J. Ray\" <ejray -at- raycomm -dot- com>)" <ght -at- MTL -dot- FERIC -dot- CA>]

Rebecca Price looked for guidance in her product manuals for heavy
machinery... and I find her domain name ("rust") highly ironic in
that context. But I digress...

It's certainly important to put the safety information up front, as
has already been done, and the first thing that should follow this is
a conceptual overview of the manual. These are likely the only
two things that your audience (owners of heavy machinery) will likely
read in their entirety and in sequence. Dangerous generalisation
number 1: It's very likely that this audience will only consult the
rest of the manual randomly, on an as-needed basis. (Verify this with
at least a few audience members!) On that assumption, the order of
the rest of the manual is mostly irrelevant: once readers know that
you've provided reference and installation sections, it doesn't much
matter where these fall in the manual, provided only that they know
how to find the sections easily. (It's certainly more logical to
have the installation section precede the user guide, of course,
but strictly speaking, that's not required because users won't
read the manual linearly.) There are obvious caveats about this,
though: for example, the index should always come at the very end of
the manual, because that's where everyone will look for it.
Similarly, the table of contents should precede the main body. Other
than that, the sky's pretty much the limit.

I'm surprised to hear your employer has only been producing 100-page
manuals so far. I agree with you that this is probably a bit skimpy,
though since you haven't mentioned what type of equipment you're
documenting, it's hard to say that with any justice. (Documenting
anvils? 100 pages might be overkill. Documenting excavators? Sounds
inadequate to me.) For example, you mentioned that the oil-change
information consists of a single instruction to change the oil every
6 months; this is clearly inadequate, since users need to know what
viscosity grades, base materials (e.g., no bio-oils, because these
will probably dissolve the standard seals), and additives are vital
to ensure the survival of their machinery. And failing to mention a
sampling protocol is also likely dangerous; the wear metal content is
probably more important than the number of machine hours on the
gauage. We're talking serious lawsuit if someone's $500 000 excavator
dies in a year because the manufacturer forgot to specify a minimum
oil standard. In my current field (forestry machinery and
operations), this sort of information is vital: the users can still
ignore you, and often do, but then you're not liable for any
subsequent problems. If you want an idea of what to include in good
docs, head down to your local Caterpillar or John Deere dealer and
purchase a replacement manual for one of their products for research
purposes; I haven't reviewed the manuals myself, but colleagues tell
me the quality is good. Moreover, companies that big have already
been through the lawsuits and figured out how to avoid them, so
they've done much of your groundwork for you.

You wondered about minimalism, and it seems like your previous writer
fell into the usual trap: minimalism NEVER means producing as few
words as possible. Minimalism is all about providing every single bit
of information the user needs to know... but not a period, comma or
witty remark more than this. When you've done this, make sure you've
presented this information effectively. A good minimalist example
might be to recommend 10W30 motor oil with anti-freezing additives
that meets a specific SAE standard; suggesting that the Exxon version
of this grade of oil is best probably exceeds the user's requirements
unless you know for a fact that no other oil will do for your
machinery. Again, check out your competitors manuals and use these
as the starting point for your research.

If your budget is big enough, I can't recommend strongly enough you
do some audience analysis. Take a day and follow a new machine to its
purchaser, and take notes as the person unpacks, installs, and fires
up the machine. Record all curses, wounds, and head scratching. That
might be all you need to do to produce a killer manual. (OK, so
"killer" might be an unfortunate word choice here. <g>) Ideally,
bring along an engineer to confirm that the user is doing things
right; you don't want to base your manual on the "typical" operator
as performed by Jim Carrey, Jerry Lewis, or Chevy Chase. <g>
--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca

Hart's corollary to Murphy's law: "Occasionally, things really do work right."