The True Cost of Poor PLC Documentation

Why the gap between “it works” and “we understand it” is where the real expense lives.

Every automation engineer has inherited a project with no documentation. You open TIA Portal or CODESYS, and you’re looking at hundreds of function blocks, thousands of tags, and not a single comment explaining why any of it exists.

The code works. The plant runs. But nobody can tell you why it works the way it does.

That gap between “it works” and “we understand it” is where the real cost of poor documentation lives. And it’s much bigger than most organisations realise.

The Problem Nobody Budgets For

When a project gets commissioned, there’s usually pressure to move on. The system runs, the client signs off, and the team shifts to the next job. Documentation gets pushed to “when things quieten down”, which of course never happens.

What gets left behind is a codebase that only the original programmer truly understands. Sometimes that’s one person. Sometimes it’s a contractor who finished six months ago and has moved to a different country.

The system runs fine for years. Then something changes. A drive needs replacing. A new product line gets added. A sensor fails and the sequence behaves in a way nobody expected. Suddenly, understanding the code isn’t optional anymore, and nobody can.

I’ve seen this happen repeatedly across twenty years in this industry. The pattern is always the same: the cost of not documenting is invisible until the moment it becomes enormous.

What It Actually Costs

The obvious cost is downtime. When something breaks and your team doesn’t understand the logic, troubleshooting takes longer. Sometimes dramatically longer. What should be a thirty-minute fix turns into a four-hour investigation because nobody knows what a particular function block was supposed to do, or why a specific interlock exists.

But downtime is just the headline number. The costs that accumulate quietly are often worse.

Training new engineers takes significantly longer when there’s no documentation. Every new team member has to reverse-engineer the system from scratch, asking the same questions as the person before them. If you’re lucky, someone remembers the answers. If you’re not, they’re guessing.

Modifications become risky. Without understanding the original design intent, engineers make changes that work in isolation but break something elsewhere. Copy-paste programming becomes the default because it feels safer to duplicate something that works than to refactor something you don’t fully understand. Over time, that creates a codebase that’s increasingly fragile and increasingly difficult to maintain.

Then there’s the migration problem. At some point, every system needs upgrading. Moving from one platform to another, or even upgrading within the same platform, requires understanding what the existing code does and why it does it that way. Without documentation, migration projects balloon in scope because every function block becomes an investigation rather than a conversion.

And in regulated industries, poor documentation creates a compliance risk. If an auditor asks why a particular safety interlock is configured the way it is, “because that’s how the contractor set it up” won’t cut it. You need to demonstrate that the control logic implements the safety requirements as specified, and that any deviations from the original design are documented and justified. If you’re operating under standards like IEC 62443 or IEC 61511, documentation requirements are explicit. Poor documentation doesn’t just cost money. In some industries, it costs certification.

The Documentation That’s Usually Missing

Most projects have some documentation. There’s typically a functional specification, maybe a set of P&IDs, sometimes a cause and effect matrix. Those are valuable, but they describe what the system should do, not what the code actually does or why it was built a particular way.

The documentation that’s almost always missing is the engineering context. The decisions that were made during development and commissioning. The workarounds that were implemented because a sensor didn’t behave as expected. The timing adjustments that were needed because two devices couldn’t operate simultaneously. The configuration choices that only make sense if you know the history.

Specifications tell you what was intended. Code tells you what was implemented. But neither tells you why the implementation differs from the spec, and it almost always does.

That “why” is what disappears when documentation doesn’t exist. And it’s the most expensive knowledge to recreate because often it can’t be recreated at all. The person who made the decision has moved on, and the reasoning died with their involvement.

What Copy-Paste Culture Does to a Codebase

Here’s a scenario I’ve seen more times than I can count. An engineer writes a function block for a pump. It works well. Six months later, someone needs to control a similar pump with slightly different requirements. Rather than understanding the original block and modifying it properly, they copy it, make a few changes, and move on.

A year later, someone else does the same thing. And again. And again.

Now you have fifteen variants of what was originally one function block, each slightly different, none documented, and nobody can tell you which differences are intentional and which are mistakes. When a bug gets found in the original logic, does it exist in all fifteen copies? Nobody knows without checking each one individually.

Capturing Knowledge as It Happens

The traditional approach to documentation treats it as something you do at the end of a project, or worse, something you do when someone finally complains loudly enough. That approach fails because the knowledge has already dispersed by the time anyone sits down to write.

A better approach is to capture engineering decisions as they happen. Using issue tracking tools, the same tools software developers have relied on for years, to create a living record of engineering decisions. When an engineer finds a fault, they log it. When they implement a fix, they document what they changed and why. When a workaround is needed because a device doesn’t behave as the datasheet suggests, that gets recorded too.

The important thing to understand here is that this doesn’t have to be extra work. The engineer is already solving the problem. They’re already thinking about why the fix works. Capturing that reasoning in a structured way takes minutes. And it creates a searchable, traceable record of every decision that was made during the life of the system.

Six months later, when someone asks “why does this valve have a three-second delay that isn’t in the spec?”, the answer exists. It’s not in someone’s head. It’s not in an email chain that got deleted. It’s in a ticket that says “valve V-401 exhibited water hammer without delay, see commissioning ticket #247.”

That’s the documentation people actually need, and it only exists if you capture it when it happens.

Good documentation like this is layered, so different people can access different levels of detail depending on what they need. Operators need to understand what the system does and what messages mean. Maintenance engineers need to understand the program structure, which function blocks control which equipment, how the sequence logic flows, where the interlocks live. And at the deepest level, the engineering record captures the design decisions: why a particular approach was chosen, what alternatives were considered, what site-specific conditions influenced the implementation.

Each layer serves a different purpose. The mistake most organisations make is trying to create one document that serves all three purposes, which means none of them get served well.

When to Bring in External Help

There’s a practical reality here: your team is already busy. The engineers who understand the system are the same engineers maintaining it, commissioning new equipment, and responding to production issues. Asking them to stop and document everything they know is rarely realistic.

This is where external expertise makes a real difference. An experienced automation engineer can read your PLC code directly, understand the logic, identify the design patterns, and produce comprehensive documentation without pulling your team away from their day jobs.

The advantage of bringing someone in from outside goes beyond capacity. Someone who approaches the code fresh, without assumptions, will identify things your team has stopped noticing. Undocumented workarounds. Inconsistent naming conventions. Logic that doesn’t match the specification. Potential failure modes that aren’t obvious when you’ve been looking at the same code for years.

The output is a document your team can actually use. A complete walkthrough of the project, from program structure and execution order down to individual function blocks, data structures, and I/O mappings. Problem areas get flagged. Improvement opportunities get highlighted. And critically, the reasoning behind the implementation gets captured before it’s lost entirely.

Start Where You Are

If you’re reading this and recognising your own situation, here’s the practical takeaway: you don’t need to document everything at once.

Start by introducing a habit of capturing decisions as they happen. When someone fixes a fault, they log it. When someone makes a modification, they record what changed and why. When a workaround is implemented, the reasoning gets written down somewhere searchable.

For the existing codebase, prioritise the areas that cause the most pain. The sequences that nobody understands. The function blocks that everyone’s afraid to touch. The sections that always come up during troubleshooting. Document those first.

And if the scale of the problem feels overwhelming, or if your team simply doesn’t have the capacity, consider getting external help. Sometimes the fastest way to solve a documentation problem is to let someone who does this professionally work through it systematically while your team keeps the plant running.

The cost of poor documentation is real, ongoing, and compounding. But it’s also fixable. The sooner you start, the less expensive it becomes.