Tips and heuristics for writing manuals for machines and equipment that require assembly, disassembly, servicing and overhaul

1. Equipment Manual Writing
Bernadette Koontz….
Society for Technical Communication Summit
May, 2014

2. Building an Artichoke – in
Reverse
• Creation of a detailed equipment manual will be
like creating an artichoke in reverse. You will
add layers (leaves) of details to the overview
(core) info.
• Details of uses, functions, tasks, servicing,
maintenance, and repairs will dictate the layers
of details (Information Mapping).
• Effective equipment manuals take into account
the intended scope, purpose, as well the skill
level/training of target audience.

3. An Outline First? Are You
Kidding Me?
• How can you make an outline when you know nothing
about the equipment?
• Let the function of the equipment and how it’s operated,
used, and serviced guide you in structuring document
content
• At the outset, the only sure thing there will be is an Intro
and/or an Overview section (which you will write last
after you understand the equipment, its function,
application, troubleshooting, and servicing) – these are
clues for the start of your research

4. Getting Started to Write and
Equipment Manual
• Who’s your audience
• If a global audience, see “Writing for International Audiences”
• Review equipment vendor literature, cull info from there
• Interview Subject Matter Experts on how equipment is to be used
• Define scope of content
• Review any applicable in-house procedures for operation and
maintenance
• Tech Writing 101 - Go to the shop floor or engineering area, with
camera, sketch pad and laptop to witness how to replace
components, service equipment (add oil), disassemble, reassemble
• Take photos, draw sketches, take notes – think visually as well as
step-wise procedurally to get the sequence correct

5. Information Mapping
• There is Information Mapping software to help you
structure and format manuals according to a hierarchy
you define
• Information mapping follows a discrete, disciplined form
of thinking where you chunk information into topics and
sub-topics to avoid 35-step procedures
• Try to keep procedures with discrete topics at a
maximum of seven main steps per topic (with up to
seven sub-steps under each main step – see hand-out)
• You can have many topics within a procedure
• You need to know your subject matter and have done
your research to use this technique

6. Warning, Cautions, and Notices
Recommend: Four types of safety advisory messages used in this manual as per the
American National Standard and ANSI 2535-6-2006:
DANGER Indicates a hazardous situation which, if not avoided, will result in death or
serious injury. This signal word is to be limited to the most extreme situations.
WARNING Indicates a hazardous situation which, if not avoided, could result in death
or serious injury.
CAUTION Indicates a hazardous situation which, if not avoided, could result in minor
or moderate injury. It can also be used without the safety alert symbol as an
alternative to "NOTICE."
NOTICE The preferred signal word to address practices not related to personal injury.

7. Checklists
Checklists are used to identify significant “must
do” tasks (helps to show “due diligence” from the
legal perspective)
Don’t overdo it, but use checklists to identify:
- Items for inspection
- Tasks and sequences to prepare or operate
equipment
- Maintenance tasks essential to servicing or
overhaul equipment-serve as a record of
repair, maintenance or overhaul

8. Summary Checklists
• These comprehensive checklists summarize
essential tasks in an entire servicing process to
walk maintainers through all required tasks, or
procedures in manual by referencing the
procedure or section in the manual.
• Each row in the checklist is a “must do” item with
the reference to the procedure or corrective
action which echos the detailed steps
• Customers really like these sorts of checklists
• So do lawyers – shows due diligence

9. Litigation Pitfalls & the Need for
Due Diligence
• Very often manuals are a weak link in
litigation (no matter how good the
manual) due to the nature of
language and how people
subjectively interpret what they read
• That is why due diligence is
important…

10. What can a Tech Writer do?
• Write instructions in a clear, active voice (Example: Install the bolt
on the flange. Not, The bolt is to be installed on the flange.) (Passive
voice makes it unclear who is to do the action and when –was it
done at the factory?)
• Provide Dangers, Warnings, Cautions, & Notices where applicable
–tell what happens if they don’t adhere to the instruction
• Keep sentences between 8 to 15 words
• Write at 8th
grade language level - Do not use college-level words,
write in simple language, simple terms –jargon okay if audience will
know the term
• Figures, photos, and illustrations with call-out to clarify instructions
• Use Summary Checklists
• For clarity, always state what you are removing a component from
and what you are installing it on

11. What can a Tech Writer do
(con’td)?
• Give right amount “Goldilocks” detail, not too little, not too much
• Make sure torque, length, weight, pressure, and any other
conversions are correct
• Make sure Subject Matter Experts review and approve content as
well as tables and figures before release of manual – get record of
sign-off
• If possible, validate the steps (walk thru the procedure) with the
Subject Matter Expert

12. Torque Tables
• Most equipment manuals require torque values for nuts, bolts, and
fasteners, fittings on hoses, etc.
• You can either refer to a standard torque table if you are sure all of
the hardware is to be torqued accordingly
• In cases where torques are specific to a unique fastener, in
domestic publications, give U.S. torque value first (in.-lb.,ft.-lb.)
followed by Newton Meters (Nm). Vice versa for manuals for non-
domestic equipment.
• Examples: 132 in.-lb. (15 Nm) 18 ft.-lb. (24 Nm)
• For torque values less than 15 ft.-lb., express torque value in in.-lb.
since the ft.-lb. torque wrench usually begins with 15 ft.-lb.
• Torque conversion link on Internet:
http://www.convert-me.com/en/convert/torque/

13. Tips
• If the equipment is complex or heavy large machinery, and it must
be disassembled, start with overview, that identifies the location of
the largest Line Replaceable Unit (LRU) to help the mechanic find
components –Refer to handout.
• If there are two ways to complete a procedure, put them in a two-
column borderless table and include the steps – Refer to handout.
• Use borderless table to match steps to applicable figure or
illustration –Refer to the hand-out.
• Chunk information by topics (information mapping techniques)
within a procedure (seven main steps – sub-steps in a step are
okay, keep sub-steps to seven or less)
• Use tables to present data or complex info
• Employ document heuristics

14. Document Heuristics
• Document heuristics, in this context, is an analysis of
content in a manual to determine if it conforms to target
audience, purpose and scope of manual, and equipment
usage
• The analysis is a method to troubleshoot a manual
• Requires proficient reading comprehension of what’s
there and what needs to be there
• The review will identify any information gaps, missing
functions or tasks or ways to present information more
clearly
• This skill takes time to develop…

15. Heuristic Analysis
This analytical technique is especially useful if you are asked to
revise an existing manual (for equipment or software)
– In addition to researching document purpose, scope and target
audience, and how equipment is to be used, etc.
– Determine if there are any new functions? Do the new functions
impact how other tasks are performed?
– Review how information is presented – examples to look for.
• Are instructions clear, written in active voice? Sequence
correct?
• Danger, Warning, Cautions, Notices
• Too many steps? Chunk info into topics.
• Would a table do a better job presenting data?
• Are checklists needed?

16. Writing for International Audiences
• Recommend writing in Simplified Technical English
• If equipment is used for land, sea, or air applications (such as
armored military vehicles, ships, or aircraft), good idea to follow
S1000D specifications
• Write short active voice sentences (especially for instructions)
• Always give metric units along with U.S. units, example: 1 in. (2.54
cm).
• Use more graphics to illustrate step, action, etc. especially for non-
English-speaking users – see hand-out
• Animated graphics good too

17. What Is Simplified Technical
English (STE100)?
An international writing specification STE100 defined by
the AeroSpace and Defence Industries Association of
Europe (ASD) which uses a finite number of specified
verbs and terminology that can be understood globally
for documentation pertaining to land, sea and air
equipment and applications.
Advantage: Can be easily and universally translated

18. XML Content
• Extensible Markup Language (XML) is good for
re-using single source document snippets; but
complicated to set up – there are new tools that
can take a Word file and make it an XML file –
but you will need a strategy for storing and
managing your content
• Otherwise, you can use a content management
system – DITA, S1000D, etc.

19. Questions & Workshop
Any questions?
Let’s look at your manuals, one-on-one!
I’ll be available by appointment during the
rest of conference for those of you who
want feedback on your manual.
There is more than one way to write an
equipment manual. I can only offer
suggestions based on past experience
and training…

20. Contact Info
Bernadette Koontz
Technical Publications Supervisor
Lycoming Engines
652 Oliver St.
Williamsport, PA 17701
bkoontz@lycoming.com
Work: 570-327-7337
Cell: 912-481-8898
Home: 570-567-7091
Home email: bb2koontz@aol.com