Know your audience
The troubleshooting guide is used by two audiences:
- Service Engineers use topics as a reference and direct action through work orders, with the goal of returning the asset to service as fast as possible.
- Maintenance Technicians follow topics as directed by a work order.
Use direct language and make each decision explicit. Tell the reader what to observe, how to choose the next troubleshooting branch, and what the outcome is.
Keep inspections and procedures in the maintenance manual
Section titled “Keep inspections and procedures in the maintenance manual”A troubleshooting topic helps Service Engineers to identify the problem. It guides the reader through diagnostic decisions and establishes what happens next. It is not a maintenance manual.
Do not write inspections or maintenance procedures in a troubleshooting guide. Use Maintenance Manual Links to find and link to the appropriate manual for the asset and hardware version.
Lead every path to one outcome
Section titled “Lead every path to one outcome”Every path through a troubleshooting topic must end in one of three outcomes:
- Return to service — the troubleshooting result supports returning the asset to service.
- Asset requires maintenance — the troubleshooting result identifies a maintenance need. Direct the reader to the applicable maintenance manual or work order instead of putting the inspection or procedure in the topic.
- Escalate — the documented troubleshooting is exhausted or engineering interpretation is required. Route the reader to a specific escalation team.
Think through the outcomes in that order as you design the flow: can the asset return to service; if not, does it require maintenance; if the topic cannot determine either outcome, who must resolve it?
See Workflow outcomes for the detailed authoring rules and examples for each ending.