Automation Project Documentation: What to Deliver

Short answer

An automation project is delivered with a document set that runs from specification to as-built: scope, P&IDs, I/O list, electrical drawings, functional description, versioned programs, FAT and SAT protocols, manuals and a change log. This documentation is what allows the plant to be operated, maintained and audited.

What documentation is for

An automation system that works but is not documented is a risk. Whoever operates it does not know why a sequence stops, whoever maintains it cannot find the sensor on the drawing, the new integrator rewrites what already existed and the auditor cannot verify anything. Documentation serves four functions: operate safely, maintain quickly, modify under control and demonstrate compliance to a customer or an auditor.

Suppliers in a supply chain increasingly ask for complete evidence per project: what was designed, who approved it, what was tested and with what result. That traceability is built during the project; rebuilding it at the end is expensive and seldom faithful.

The document set, by phase

Phase	Document	Essential content
Definition	Scope and requirements specification	What the system does, supply limits, standards, environment
Definition	Responsibility matrix	Who delivers, approves and tests each part
Basic engineering	P&ID and block diagrams	Equipment, loops, instruments, interlocks
Basic engineering	One-line diagram and load balance	Supply, protections, power ratings
Detail engineering	I/O and instrument list	Each signal with tag, type, range, location and description
Detail engineering	Power and control electrical drawings	Schematics, terminal blocks, wiring, numbering
Detail engineering	Network architecture and address plan	Switches, zones, addresses, protocols
Detail engineering	Functional description	Modes, sequences, alarms, safe states
Software	Source programs and configurations	Version, comments, tag list, drive parameters
Testing	FAT and SAT protocols and records	Cases, acceptance criteria and recorded results
Delivery	As-built and manuals	Final drawings, operation and maintenance manuals
Operation	Change log and backups	What changed, who approved it, versioned copy

Document management also requires a coding and revision scheme: each document with code, title, revision, date, author and approver, and a master list showing which revision is current. Site changes are recorded with a change request form, approved before execution and closed when all affected documents are updated. Without that control, three versions of the same drawing coexist and nobody knows which one governs.

The symbols and identification on drawings follow the convention adopted for the project. The guide on one-line diagrams of a plant shows how the power part is presented.

The I/O list as the backbone

The input and output list is the most reused document. From it come the PLC cards, the terminal block drawings, the SCADA screens, the points to test at FAT and SAT and the alarm list. Each row carries at minimum: unique tag, description, signal type, range and unit, physical location, panel and terminal, the equipment it belongs to, safe state on failure and comments. A consistent naming convention avoids translations between drawings and program.

Besides the list, terminal block and cable numbering must be unique and traceable: a cable carries an identifier that appears on the drawing at each end, in the cable list and on the physical label. When a signal fails at three in the morning, whoever arrives at the panel must be able to follow it from the sensor to the card without opening the program.

A useful practice is that the tag name is the same on the drawing, in the list, in the PLC and in the SCADA. When one changes, all change, which is why it is handled under change control.

Functional description: before programming

This is the document that avoids the most arguments when done well. For each unit or equipment, it writes down:

Operating modes: manual, automatic, local, remote, maintenance.
Normal and emergency start and stop conditions.
Step-by-step sequences, with supervision times.
Interlocks and permissives, indicating which are safety-related.
Alarms, with their priority and the expected operator action.
Behavior on power failure, communication failure or instrument failure.

A good test: two engineers who did not take part in writing it must arrive at the same logic by reading it. Complex sequences are complemented with a state diagram or a function chart. For safety functions there is additional documentation, explained in the guide on functional safety, SIL and PL.

Acceptance tests: FAT and SAT

Protocols are written before the test and agreed with the customer. Each case carries: objective, initial condition, action, expected result and space for the actual result, the witness record and the date. Deviations are logged with their corrective action and closure.

The FAT tests what can be tested without the plant: logic with simulated signals, communications, screens, alarms and forced faults. The SAT tests the real installation: each loop from the field, rotation direction, travel limits, real times and integration with other systems. The guides on standards for commissioning, FAT and SAT and on commissioning levels extend the framework, and the commissioning dossier describes how the final package is assembled. If there are cybersecurity requirements, cybersecurity tests in FAT and SAT are added.

As-built, manuals and handover

The as-built reflects what was actually installed and programmed, not what was designed. It includes corrected drawings, the final I/O list, programs with the version loaded in each controller, drive, relay and switch configurations, and the address plan. To that are added operation and maintenance manuals, recommended spare parts lists, calibration and test certificates, and warranties.

The format must be editable and readable in the long term: the source program in the manufacturer’s format, drawings in an editable format as well as PDF, and a copy of the configuration software in the version used.

Illustrative numerical example

Data invented to show the effect of consistent documentation.

A processing line has 420 signals: 180 digital inputs, 120 digital outputs, 80 analog inputs and 40 analog outputs. If the FAT verifies each signal in 3 minutes on average, that is 21 hours of testing. At the SAT, with field checking, 8 minutes per signal would add up to 56 hours. With a clean I/O list and the protocol generated from it, the duration approaches those figures. Without a reliable list, each difference between drawing and program is resolved on site, with several extra minutes per signal on 10% of the points, which means about 6 to 8 additional hours of stopped equipment.

Documentation pays for itself at commissioning.

Change management after handover

Documentation degrades if it is not maintained. Each later modification, such as a new signal, a setting change or an equipment replacement, follows the same cycle: request, impact assessment, approval, execution, test and update of drawings, I/O list and programs. A versioned copy of each program and configuration is kept, with date and responsible person, and it is periodically tested that the backup can be restored. That discipline is what allows a return to a known state after a failure or a wrong change.

Common mistakes

Programming before agreeing the functional description.
Site changes that do not return to the drawings or the I/O list.
Delivering only the compiled program, without source or comments.
Several versions of the program without knowing which is in the controller.
Test protocols written on the day of the test.
Results without date, without reference to the equipment, or without the measuring instrument used.
No backups of drive, relay and switch configurations.
Documents without code or revision, impossible to audit.

Handover checklist

Scope and requirements approved.
P&IDs, one-line diagrams and electrical drawings at final revision.
I/O and instrument list consistent with drawings and program.
Network architecture and address plan.
Functional description approved.
Source programs and configurations with version, and a copy in a safe place.
FAT and SAT protocols completed, with deviations closed.
As-built, manuals and spare parts lists.
Training recorded.
Change management and backup procedure delivered.

How we support you

We produce the engineering and documentation within our engineering design and studies service, and prepare and run the protocols in testing and commissioning, in Colombia or elsewhere on request, with a traceable package for customer audits. We quote according to the scope of your project.

References

IEC 61131-3, Programmable controllers: programming languages (program organization).
ISA-5.1, Instrumentation symbols and identification (loop and tag identification).
IEC 61082 and IEC 81346, preparation of documents and reference designation (overview).
Common FAT and SAT practice in automation projects.

Frequently asked questions

Which document defines what the system must do?

The functional description, which writes down the control behavior: operating modes, sequences, interlocks, alarms and safe states. It must be agreed before programming, because it is the basis of testing and acceptance.

What is the difference between FAT and SAT?

The factory acceptance test (FAT) is done before shipment, with the system assembled and simulating the process. The site acceptance test (SAT) is done once installed, with the real process and the final interfaces. Both follow a protocol approved in advance.

When is the as-built delivered?

At project close, after commissioning, with all changes made on site reflected in drawings, I/O list, programs and configurations. Delivering the original design as if it were the as-built is a frequent cause of later problems.

Who owns the PLC code?

The contract must define it. It is wise to require delivery of the source program, with comments, version and the needed passwords or permissions, and not only the compiled program. Without those, the owner depends on the integrator for any modification.