TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
