LADX
Start free
← Resources
Practice·7 min read·

Documentation people actually read

Four documents carry almost all the value, and most projects produce them in the wrong order.

Short answer

Four documents carry most of the value: an I/O schedule, a control narrative, the tag list with comments, and a record of what changed and why. The I/O schedule and tag list are mechanical and should be generated. The narrative and the change record are where the engineering judgement lives and cannot be automated.

The loop that makes it usableModel writesany providerCompiler answerspass / failYou read itonly if it passedfailures go back, with the errorsthis is what makes a free model good enough

Most projects produce documentation because the contract requires it, which is why most of it is never opened again.

The four that matter

  • I/O schedule. Every point, its address, its device and where it is. Mechanical, generatable, and the first thing anybody wants at three in the morning.
  • Control narrative. What the machine does, in sentences, for somebody who cannot read ladder.
  • Tag list with comments. The names, and what they mean.
  • Change record. What was altered, when, and why.

Comment the why, never the what

XIC Start_PB does not need a comment saying it examines the start button. It needs one only if there is something surprising about it.

The comment worth writing is the one the code cannot express: 'guard must remain closed two seconds after cycle end, added after the 2019 incident'. Nobody can recover that from the logic.

Generate the mechanical parts

The I/O schedule and the tag list are derived from the program. Writing them by hand guarantees they drift out of date the first time somebody adds a point.

The narrative and the change record are the ones worth a person's time, because they hold information that exists nowhere else.

Common questions

What is a control narrative?
A plain-English description of what the machine does and under what conditions, written for someone who cannot read ladder. It bridges the gap between the specification and the code, and it is the document maintenance staff actually open when something behaves unexpectedly.
How detailed should PLC comments be?
Comment the intent, not the mechanism. 'XIC Start_PB' needs no comment. 'Guard must stay closed for two seconds after the cycle ends, added after the 2019 incident' is the comment that matters, because the code cannot express why.

Keep reading