WRITING FOR HARDWARE You Can’t Always Touch It

THE MYTH – “HARDWARE WRITING IS EASY BECAUSE…”

“You can turn it on!” “You can pick it up and turn it over!” “Hardware is simpler than software.” “You can touch it!”

“YOU CAN TURN IT ON!”

“From where????”“How????”

“YOU CAN PICK IT UP AND TURN IT OVER!”

“But it weights three Thousand pounds!”

“HARDWARE IS SIMPLER THAN SOFTWARE”

“Wait…whichWire?”

“YOU CAN TOUCH IT!”

“I know your job is to write about the airplane engines. My job is to shoot you if you try to touch them.”

THE REALITY?

Myths may be true about small hardware systems associated with high technology.

But hardware covers a much broader spectrum than just “things related somehow to software.”

SO…WHAT IS HARDWARE DOCUMENTATION?

HARDWARE DOCUMENTATION MAJOR TYPES

Operator Manuals Inspection and/or Repair Manuals Parts Lists Manufacturing/Assembly Documents Service Bulletins

OPERATOR MANUALS

OPERATOR MANUALS

Not unlike software manuals Aimed at the product’s primary user Safety section first Overview section second May include troubleshooting

OPERATOR MANUALS – EXAMPLES

Transportation, Aviation, Shipping Heavy Equipment Telecommunications Equipment and

Subsystems High Technology Systems Medical Systems Consumer Goods

OPERATOR MANUALS –USE CASE

Possibly easier to develop because it is easier to visualize how the product is used

End users can be identified by profession and expected tasks

OPERATOR MANUALS –USE CASE

Both are drills…but the end useIs very different.

OPERATOR MANUALS – SAFETY STANDARDS

ANSI Z535.6 ATA Series MIL-STD-38784 Many others for different

industries

Choose a spec…stick to it!

OPERATOR MANUALS – ANSI 535.6

Danger

This will kill or seriously injure

Warning This may Kill or injure

Caution (with alert) This may cause moderate injury

Caution (without alert) This will break something

Notice Good to know

OPERATOR MANUALS – SAFETY MARKINGS

LABELING• Product may have

labels concerning safety issues.

• Be sure the label and the corresponding text are consistent.

• Use consistent hazard icons.

INSPECTION MANUALS

INSPECTION MANUALS

May be combined with repair manuals. Includes wear and tear limits on parts. Covers known or predicted trouble points. Systems with wear and tear that exceeds

inspection limits generally are inducted into the repair cycle.

INSPECTION MANUALS – BASIC FORMAT

Tell the user how to gain access to the component (for example, partially disassemble the product).

Tell the user how to perform the inspection. Tell the user what the limits of wear/tear are. Tell the user how to restore the system to

normal function when done inspecting.

INSPECTION MANUALS –TYPES OF INSPECTION (STRUCTURAL)

Visual X-ray Magnetic particle Ultrasound “Coin tap”

INSPECTION MANUALS –TYPES OF INSPECTIONS (ELECTRONIC)

Voltage levels Electronic test points Cable pin out measurements

REPAIR AND MAINTENANCE MANUALS

REPAIR/MAINTENANCE MANUALS

Remove first, then replace Pictures, pictures, pictures List all tools List all consumables List all expendables

REPAIR MANUALS –LEVELS OF REPAIR

Multiple docs may be needed for a single subject, depending upon the audience.

Repair manuals are often geared toward what the user is authorized to do. Lowest Level: “Field” repairs, routine maintenance. Intermediate Level: Repair Shop. Highest Level: “Factory style” rework and machine

work.

REPAIR/MAINTENANCE – FIELD

Troubleshooting is the first order of business. First figure out what component has failed. After that, user can proceed.

Fluid replacement, cleaning, preventive maintenance. Major subassemblies removed and replaced, broken

parts sent to higher level for repair. Level of procedure detail is light, because operations

are relatively simple.

REPAIR/MAINTENANCE –FIELD

Cable pin outs are important troubleshooting tool.

Test points on circuit cards are also important.

REPAIR/MAINTENANCE –INTERMEDIATE

Significant disassembly and parts removal/replacement.

Open the box, remove and replace components.

This level of repair requires the most extensive detail in the repair procedures.

REPAIR/MAINTENANCE – “FACTORY STYLE” (DEPOT)

Major overhaul/major repair. Can involve fabrication of new parts, machining,

welding. Helpful to have an understanding of these techniques

– can often be learned at community colleges. Manuals tend to be compilations of data as opposed

to specific procedures. Why……?

REPAIR/MAINTENANCE – “FACTORY STYLE” (DEPOT)

….because Users at this level are generally well trained in their

craft. They know in general how the repair is done, but need

specifics dealing with component composition, drilling, grinding, welding.

Give ‘em the data in a clear format, they will know what to do.

THE OLDER THE SYSTEM, THE BIGGER THE MANUAL

Unlike software, the older the hardware gets often the repair manuals get bigger.

Early in the system life cycle, failures are managed by removal/replacement.

But as systems age, it’s more economical to develop repairs…and with age, components with common failures rate new procedures for repair.

AS AN EXAMPLE…

Boeing Aircraft Company manufactured 12,000 B-17 “Flying Fortress” airplanes, ending in 1945.

About a dozen still fly. Boeing still maintains

and updates B-17 tech manuals as needed.

PARTS LISTS

PARTS LISTS – MANY NAMES, SAME FUNCTION

Parts List Parts Catalogue Illustrated Parts Breakdown (IPB) (USAF) Illustrated Parts List (IPL) (USN) Repair Parts & Special Tools List (RPSTL) (US

Army)

REPAIR/MAINTENANCE – PARTS LISTS

“Illustrated Parts Breakdown” Equal parts art and science

PARTS BREAKDOWN

• Exploded view of object

• Reference Number

• Part Number

• Quantity

• Part Name

IPB: THE GOOD NEWS

Creation of parts lists made easier by current tools Illustrations and parts lists can be generated by

illustration tools that interact with CAD models Configuration management tools (Oracle Agile)

also useful in generating coherent parts lists Of course, this assumes the engineer was thinking

about the parts manual during design.

MANUFACTURING PROCEDURES

MANUFACTURING/ASSEMBLY DOCUMENTS

Simpler design, heavier on graphics

Breaks procedure down to lowest level

Electronic versions benefit greatly from animation.

MANUFACTURING/ASSEMBLY PROCEDURES

Consistent manufacturing procedures create assurance of quality in the product.

May be required to maintain ISO certification.

MANUFACTURING/ASSEMBLY DOCUMENTS – MOST LENGTHY OF ALL

ANDE: Portable DNA Analyzer by Analogic Operator manual about 30 pages Manufacturing docs…closer to 700 pages

Aviation Manufacturing Rule of Thumb For major airliner, printed doc set (flight and

maintenance) occupies 50-60 feet of shelf space Manufacturing procedures and specifications exceed

weight of the aircraft.

MANUFACTURING INSTRUCTIONS –THE FINAL FRONTIER

SERVICE BULLETINS

SERVICE BULLETINS –UPGRADES

Software equivalent – upgrade for new release Typically part of an upgrade kit including parts Could be equipment with new features Could be driven by safety requirements

SERVICE BULLETINS –UPGRADES

Typical Format: Parts Inventory List of Tools Removal of Old Components Parts Disposal or Rework Information Installation of New Components

SERVICE BULLETINS –INSPECTIONS

Arise as a result of a newly discovered flaw or potential breakdown of equipment.

Usually have a very quick turnaround. Often paired with a repair service bulletin

issued to correct the problem. Most commonly seen example: automobile

recalls.

SITUATIONAL CONSIDERATIONS

NOT ALWAYS AN IDEAL ENVIRONMENT

SITUATIONAL CONSIDERATION –WHERE WILL THE WORK BE PERFORMED?

Indoor Setting? Confined Workspace? Elevated Workspace? Outdoors?

SITUATIONAL CONSIDERATIONS –SAFETY

Electrical hazards Temperature hazards Moving parts Toxic chemicals Radiation Noise

SITUATIONAL CONSIDERATIONS – USER PROTECTIVE GEAR

Necessary to list Necessary to add

statements about wearing

Necessary to consider impact on user’s movement

SITUATIONAL CONSIDERATION –ONLY ONE WAY IN

SITUATION CONSIDERATION – WHAT IS THE BEST DELIVERY MEDIA?

Paper might be best if users need to spread out.

Electronic might be best if users must carry multiple volumes or if updates are frequent.

ILLUSTRATIONS

WORTH A THOUSAND WORDS

HADRON COLLIDER VIEW

HADRON VIEW REWORKED

NOT A GOOD WAY TO DO THIS!

ILLUSTRATIONS – RIGHT FROM THE SOURCE

ILLUSTRATIONS –ANIMATION & VIDEO

Relatively easy using graphics tools that interact with solid models.

Animations can be delivered separately or contained in PDF

Self-standing video presentations can be created.

ILLUSTRATIONS –VIDEO PRODUCTION

Sometimes the best “manual” is a video demonstration.

Script, shot sheet, plan in advance. One page script = one minute video. Call a pro or take some courses.

SOURCE DATA

SOURCE DATA -ENGINEERING DRAWINGS

SOURCE DATA – SOLID MODELS

SOURCE DATA –WIRING DIAGRAMS

SOURCES– ENGINEER SME

As with software, the engineers are the primary source of information.

Go to for answers on quantities, types, overviews, and the big picture.

SOURCES – PRODUCTION FLOOR

Manufacturing team makes it real. Can often explain on a level more like

your audience Often the first to find things that will

need to be changed.

SOURCES –END USER SME

Knows the material Knows the situation Offers practical advice Knows what is likely to

trip up other users.

JOB OPPORTUNITIES

WHO NEEDS HARDWARE MANUALS?

Aerospace and defense Transportation/Automotive Robotics Manufacturing Consumer

…in short….just about everybody.

AND IN CONCLUSION…

NEW MEDIA

Have been saying “manuals,” which implies paper, but this is not always true.

Mobile presents new opportunities for workers to bring volumes of data in a light and portable format.

Technology allows interactive documentation – perform an inspection and automatically order repair parts and tools.

NEW MEDIA – BEYOND THE BLEEDING EDGE

Google – Magic Leap https://youtu.be/kPMHcanq0xM

Oculus Rift – some time next year? Lockheed Martin already using this concept

in F-35 Lightning II aircraft assembly procedures.

On smaller scale, Audi already releasing iPhone VR owner’s manual.

…INTANGIBLE REWARDS

ANY QUESTIONS?