The red beacon means an E-stop is active. Every piece of automation documentation says so. What it rarely says is which of the twelve pull cords along a 400-foot sorter tripped, how to find it, who is allowed to reset it, and what has to be true before someone presses Start.
That gap, between what a system does and what a person should do about it, is where a lot of automation downtime gets made. Descriptions of operation (DOOs) and OEM manuals are written to explain how equipment is meant to behave. The people who keep it running need something else: the steps to recover it when it stops.
We recently reviewed two sets of sorter documentation line by line, looking for one thing. Could an operator, a technician or a controls engineer recover the system from each alarm using only what was written? This post covers what we found, where the gaps sit across the software, controls, electrical and mechanical layers, and what end users should ask for before they sign off on a system.
What two document reviews found
The first was a 26-page DOO from 2025 for a pop-wheel shipping sorter with infeed’s, merges and a spiral. The second was a current OEM controls manual (78 pages) and maintenance manual (118 pages) for a sliding-shoe sorter. Different vendors, different eras, very different page counts.
We tested every alarm, indicator, operating mode and recovery scenario against four questions. Is it defined? Is the cause explained? Are there steps someone can follow? Is there a way to confirm the fix worked?
The newer manuals were better. The maintenance manual includes nine troubleshooting cards and solid remove-and-replace procedures. But more than seven times the page count bought 16 points of recovery coverage. The content that keeps a system running is a different kind of content, and neither package was built around it.
Where the gaps sit, layer by layer
A modern material handling system stacks four layers: the software that decides where product goes (WMS, WES, WCS), the PLC controls that make it happen, the electrical system that powers it, and the mechanical equipment that moves it. Faults rarely respect those boundaries. Documentation usually does.
Software: WMS, WES and WCS
Both document sets pushed fault detail up to the software layer with lines like "the specific fault can be viewed in the WCS" or "refer to the software documentation." Neither named a screen, and neither package included the software guide.
The gaps we see most often at this layer:
• Fault ownership. In the DOO, induction halts after repeated no-reads are detected by the host system, not the PLC. The document never says who resets the halt, or where.
• Undefined thresholds. "Too many consecutive no-reads" triggers a halt. How many is too many isn't stated.
• Interface behavior. What happens when the host doesn't answer a sort request in time, where the carton goes, and how that shows up on the floor.
• Order reconciliation. When operators pull cartons off a sorter to clear a jam or gridlock, nothing explains how to re-induct them or update the WMS. Orders go missing here.
• Lane configuration. "No matching lane" errors point to software setup, with no owner named for checking it.
Controls
This is where the missing alarm list hurts most. Neither document set included alarm IDs, HMI message text, trigger conditions, timer values or reset locations. Without that, every fault starts with a search.
• One light, several faults. In one manual, flashing amber meant a jam, an item on the guard, a missing slat detection plate, or a nose bar pop-up. Four faults, one pattern.
• Contradictions. In the DOO, one section said a drive fault shows solid amber. Another said solid amber means lost communications.
• Missing values. Jog speeds marked TBD. Jam timers left out. A sleep timer given as 10 minutes in one section and 15 in another.
• No network map. Device replacement procedures depend on IP addresses that appear nowhere in the package. They will need to corelated from the Redline commissioned electrical drawings.
• No backup and restore. Nothing on recovering the PLC program, drive parameters or I/O configuration after a failure. Except a reference to high level manufactures manuals.
• Safety diagnostics. One manual warns that the safety circuit can stay faulted with every E-stop healthy, then gives no way to find the faulted node.
Electrical
• Isolation points. Both documents told technicians to lock out "the motor disconnect." A sorter has several energy sources: the main drive, spur and herringbone drives, 480 V distribution panels, 24 VDC divert supplies, compressed air, and stored energy in the chain.
• Drive faults handed off to "the manufacturer's manual," with no drive model, fault list or parameter set.
• Power supply trips answered with "inspect for wiring issues" and no method to isolate the shorted branch.
• Restart after a power loss or PLC fault. Not covered in either set.
Mechanical
Mechanical content was the strongest of the four layers, especially the remove-and-replace procedures. The gaps sit at the edges:
• "Shorten the belt" or "shorten the chain" with no tension spec or procedure reference.
• Divert component wear limits that aren't stated.
• No critical spares list, even where every part number is already in the manual.
• Troubleshooting cards that stop at the cause and never say how to confirm the repair held.
The pattern across layers
WMS / WES / WCS
"View the fault in the software"
Screen path, fault owner, reset method, order reconciliation
Controls
"Amber light = jam"
Alarm list: ID, trigger, timer, beacon pattern, reset point
Electrical
"Lock out the motor disconnect"
Isolation matrix by zone and energy type
Mechanical
"Shorten the belt"
Tension spec, procedure, wear limits, part numbers
Safety
"Reset the E-stop and press Start"
Device map, reset authority, pre-start sweep
Why the documents read this way
None of this comes from carelessness. It comes from when and why the documents get written.
A DOO is usually written during design, by a controls engineer, to describe intended behavior and give everyone something to test against at acceptance. It is a specification. Once the system passes, the DOO tends to freeze at Rev 0. Our 2020 example still had an empty open-issues table and an unsigned approval block.
OEM manuals are written per product, not per site. They cover the equipment inside the vendor's scope and point outward for everything else: the commissioning manual, the installation manual, the as-built drawings, the software guide. In the second review, the manuals referenced a commissioning manual about a dozen times. It wasn't in the package.
Then the people who know how to recover the system, the commissioning techs who cleared the first hundred jams, move on to the next project. Their knowledge leaves with them.
The result is a system documented box by box, by different authors, with the seams left open. Faults live in the seams.
What good looks like
The fix starts with a different unit of documentation: the alarm. For every alarm and indicator state, the site needs a record that passes four tests:
1. Defined. The code, message and light pattern, in plain language.
2. Explained. What causes it, and what stops upstream and downstream.
3. Actionable. Steps for each role that will meet it, in order, with the safety precautions named.
4. Verifiable. What "back to normal" looks like.
Each record also has to work for three different readers:
Operator
What is it telling me, and what am I allowed to do?
Meaning, first response, reset steps, when to call maintenance
Technician
Where is the fault, and how do I fix it safely?
Likely causes, device location, isolation and test steps, parts, restart
Controls engineer
Why did it happen?
Trigger logic, timers, tags, I/O, backups, root-cause paths
A one-page alarm card with those fields, built from the PLC alarm export and checked on the floor, does more for uptime than another hundred pages of system description. It also gives a knowledge base or an AI assistant something solid to answer from. A model can only be as confident as the content behind it.
How AurelicAI builds the knowledge base during ServiceEdge_AI commissioning
At AurelicAI, we don't treat documentation as a prerequisite the customer has to sort out before ServiceEdge_AI goes live. Closing the recovery gap is part of commissioning. ServiceEdge_AI is an on-premise AI platform that brings together PLC code, electrical schematics, OEM manuals and site knowledge, so operators, technicians and senior technicians can get answers through a chat on any shift. A chat is only as good as what sits behind it, so the first job is building that content.
1. Collect everything that exists
Commissioning starts with a site assessment and a documentation request: the DOO, OEM manuals, electrical and network drawings, the PLC program and alarm export, drive parameters, the WMS/WCS interface specs, CMMS work order history and 90 days of alarm history. Most sites have more than they think, spread across more places than they'd like.
2. Ingest and audit
ServiceEdge_AI ingests the document set, and we audit it alarm by alarm against the four tests above. The output is a punch list ranked by safety risk and downtime, sorted by role and by who holds each missing answer: the OEM, the integrator, site maintenance, operations or EHS. This is the same review behind the numbers earlier in this post.
3. Capture what isn't written down
Much of what's missing lives in people's heads. We run structured knowledge-capture interviews with the technicians who clear the jams, the operators who see the alarms first, and the controls engineers who know the logic. Each session targets specific gaps from the punch list, with follow-up questions that dig into the real recovery steps and workarounds. Field walks confirm device locations, beacon and E-stop positions, and labels against the drawings.
4. Write the recovery content
From those answers we write the documents the DOO left out:
• Alarm cards for every alarm: meaning, cause, first response, reset, verification, escalation
• Troubleshooting flowcharts for the priority faults
• A beacon and indicator legend covering every pattern
• A LOTO matrix by zone and energy type
• Restart procedures after power, air, comms and PLC faults
• Software-layer recovery: fault ownership across the WMS, WES, WCS and PLC, plus order reconciliation after a jam
Each piece is tagged by role and linked to the device, I/O point, drawing and part number it refers to. That linked model of the site, from alarm to device to procedure to part, is what lets the chat answer a specific question rather than return a document.
5. Validate before it goes live
Site subject-matter experts review the content before operators and technicians see it, and EHS signs off anything that touches safety, lockout or E-stop recovery. Each item goes under version control, so the knowledge base changes when the system changes.
6. Answers by role, through a chat
The same alarm needs a different answer for each person who meets it. An illustrative example:
Operator
"The infeed beacon is flashing amber. What do I do?"
What the pattern means, which faults it can be, the first safe action, the reset station, and when to stop and call maintenance
Technician
"Divert failures keep repeating at one lane."
Likely causes in order, LOTO points for that location, test steps, part numbers, and how to confirm the fix
Senior technician
"Why does the sorter go into gridlock prevention?"
The trigger logic, thresholds and timers, the PLC tags involved, and the root-cause paths when it repeats
7. Keep it current
Every fix (RCA) becomes new knowledge. Resolutions from work orders and chat sessions feed back into the knowledge base, and alarm history shows which alarms drive the most downtime and where content needs to go deeper. Reporting on repair time by alarm class shows whether the knowledge base is moving uptime and SLA attainment.
The result is a site that keeps its recovery knowledge when people change shifts, roles or employers, and a team that can recover the system at 3 a.m. with the same confidence as the day shift.
The bottom line
Automation performance is measured in uptime, SLA attainment and mean time to repair. All three depend on how fast a person on the floor can get from "the light is amber" to "the line is running." In both systems we reviewed, the documentation got them only part of the way.
Celtic Innovations audits DOOs and OEM manuals for exactly these gaps. AurelicAI closes them as part of every ServiceEdge_AI commissioning, so the knowledge base your operators, technicians and senior technicians chat with is built on recovery content, not just system descriptions. If you want a second set of eyes on your documentation,
