A PLC program may seem clear during initial commissioning, but the person investigating a fault six months later may be a different engineer. Documentation is not intended to restate all the code; it should make the relationship between machine behaviour and software visible. A good handover package reduces guesswork and risky experimentation by maintenance teams.
01Explain why the code acts, before explaining what it does
Q0.3 becomes active often simply repeats the code itself. By contrast, “Prevents the cutter from advancing before the product is clamped; stops the cycle if clamping confirmation is lost” explains the functional intent. Interlocks, timeout settings and restart conditions particularly need explanation.
Symbolic names also express this intent. If equipment, functions and states follow a consistent naming structure, the program's language remains consistent across stations. The manufacturer's programming guide provides a sound basis for technical decisions such as block interfaces and data structures; add the project's own naming conventions on top of it.
02The I/O list should be a living document
The list should contain more than input and output addresses. Match physical equipment labels, terminal details, signal types, normal states and software symbols. For analogue inputs, also specify the engineering range and disconnected-sensor behaviour. A signal with one name on the schematic and another in the program wastes time during servicing.
| Field | Example content | Benefit |
|---|---|---|
| Equipment | Station 2 clamping sensor | Identifies the physical point |
| Symbol | Clamp2_Closed | Makes searching the code easier |
| Logic | Clamping is closed when active | Reduces NO/NC interpretation errors |
| Connection | Module / channel and terminal | Provides field mapping |
| Fault behaviour | The cycle waits if confirmation does not arrive within the time limit | Explains the expected outcome |
03Make the state machine visible
An automatic cycle can be described through defined states, such as idle, preparation, processing, unloading and fault, instead of a combination of unexplained bits. Specify the conditions, cancellation reasons and timeout for each transition. The conditions under which the machine may return from manual to automatic mode are particularly important.
For example, suppose a detected part triggers a clamping command and processing begins once confirmation arrives. If confirmation does not arrive, document not just an alarm code but also the issued command, the expected feedback and the conditions for retrying. This reduces the need for maintenance personnel to force cycle bits manually to advance the machine.
04A backup file is not a rollback plan
Copying a project folder is only a starting point. Manage the engineering software version, device firmware, libraries, licence requirements and necessary access information as well. Do not put access passwords in publicly visible comments; store them according to the site's access-management rules.
A rollback plan explains which file belongs to which device and how to restore the previous state if a change fails. HMI, drive, recipe and network settings may be stored separately from the PLC project. The package must enable the entire system to be restored. Verify that the backup is usable in a safe test environment or during planned maintenance.
05The change log is maintenance's memory
Instead of names such as “latest version” or “latest_latest”, maintain a change log linked to dates and versions. Record the reason for each change, affected blocks, tested scenarios and the approving party. Increasing a timer from 2 seconds to 5 seconds may look minor but could conceal a mechanical or process problem; the rationale matters.
If version control is used, choose a method suited to the manufacturer's file structure. Not every project supports line-by-line comparisons. In such cases, assess readable exports, version tags and test reports together. Knowing that a file changed does not explain why its behaviour changed.
06The essential handover package
- Source project, version details and a verified restoration method.
- I/O and network-device lists consistent with the electrical schematics.
- Automatic cycle, mode transitions and critical interlocks.
- Alarm descriptions and a safe diagnostic sequence.
- HMI / drive backups and parameter sets.
- Acceptance tests, known limitations and change history.
Documentation quality is measured not by page count but by how well it helps another person understand the system safely. If machine changes are not recorded, even the best initial documentation soon becomes outdated.
07Example verification scenario
Imagine a maintenance engineer investigating why a cycle is waiting at its third step. If the state list identifies the expected sensor, permissive conditions and timeout, diagnosis leads directly to measurements. In a program consisting only of addresses, the same information must be traced across several blocks. During handover testing, someone who did not write the project can be asked to locate an example fault using the documentation. This helps assess the document's usefulness rather than merely its existence.
Technical references and further reading
For product- and version-specific values, the relevant manufacturer's current documentation should be taken as the reference. The calculations and scenarios above are engineering examples for illustrative purposes.
