The documentation problem
Walk into almost any industrial facility and ask to see the documentation for the PLC system. What you usually get is one of three things: a printout of the ladder logic from five years ago that may or may not reflect what is currently running, a set of drawings that were as-built at commissioning and never touched since, or a blank look.
This is not unique to any particular industry or any particular size of facility. It is the norm. And it creates real problems: fault diagnosis takes longer because the engineer has to reverse-engineer the program logic before they can identify the fault. Modifications are made without understanding the full effect because the dependencies between routines are not documented. Skilled operators and maintenance staff leave, and their knowledge of the system quirks leaves with them.
Good documentation is not a luxury. It is what makes a control system maintainable by the next person who works on it.
What should be documented
The program itself
A PLC program with no comments is a sequence of logic operations with no explanation of why they are there. The engineer who wrote it understood the intent — they are not the one who needs the comments.
Every routine in the program should have a header comment explaining what it does, what its inputs are, and what it produces. Complex rungs or sequences should have inline comments explaining the logic. Anything that looks wrong but is intentional — a latching interlock that only resets on a specific condition, a timer with an unusual preset — should be explicitly noted.
Comments do not need to be long. A single sentence that tells the next engineer why this rung is here is worth more than a paragraph that describes what it does (the code already shows what it does).
The I/O list
The I/O list maps every physical signal to its PLC address, description, engineering units, and wiring reference. A good I/O list lets an engineer trace a signal from the field device to the PLC register to the program rung without needing to manually hunt through drawings and the program in parallel.
The I/O list should be a living document — updated whenever field devices are added, removed, or modified. An I/O list that is six months out of date is almost as unhelpful as no I/O list at all.
The as-built drawings
Panel drawings, cable schedules, and loop diagrams should reflect what is physically installed — not the original design intent. The gap between design drawings and as-built reality grows over time as modifications are made in the field without being recorded.
Every modification to a control system should include an update to the affected drawings. This discipline is easy to maintain at the time of a modification and very difficult to reconstruct afterwards.
The sequence and interlock descriptions
For process control applications, there should be a written description of what each sequence does — what states it can be in, what conditions cause transitions between states, and what the interlocks are. This does not need to be a formal specification document. A one-page narrative description of the process sequence is enough.
This description is what an operator or maintenance person reads when they are trying to understand why the system is behaving in a way they did not expect.
What gets handed over at the end of a project
When Beetle Engineering completes a control system project, the standard hand-back documentation includes:
- PLC program: fully commented, version tagged with commissioning date, loaded and running on the installed hardware
- I/O list: complete signal listing with descriptions, scaling, wiring references, and any modifications made during commissioning
- As-built drawings: updated to reflect the installed system, RPEQ-stamped where required
- Commissioning record: loop test results, functional test sign-off, outstanding punch list items
- Maintenance guide: brief document covering how to access the program, common fault codes and their meaning, and first-response procedures for the most likely faults
This is the documentation a maintenance team can actually use. It is not the documentation that is produced by exporting whatever the software tool generates by default.
The cost of not having it
The cost of poor documentation shows up during fault response. A production fault that should take an hour to diagnose and resolve takes four hours because the engineer has to map out the program structure before they can understand what is wrong. A fault call at 2am on a weekend costs significantly more per hour than a fault call during business hours.
Good documentation is an investment that reduces the ongoing cost of maintaining and supporting a control system. It also reduces the dependency on any single engineer — a system that is well documented can be worked on by an engineer who has never seen it before.
That is what documentation is for.