The Functional Specification: Critical before, during, and after a Project

Team at white board discussing functional specifications

A functional specification, or functional spec, is a vital document to any project. It ensures that all parties, the integrator, the system designer and the end customer, are all in agreement on how the system is supposed to work. While it may seem that a functional spec is only useful at the beginning of a project, it is the centerpiece of the project before, during, and even after the project is complete.

A functional spec often gets confused with a control narrative. A control narrative gives the high-level process overview of how a system is supposed to function. It may list out some details, but in general it is more of a high level summary of the system. The functional spec is far more detailed.  It describes of how each piece in a system works and how those pieces work together to make the system perform.  A good functional spec also defines what should happen when the system is not working properly. It also provides the nitty gritty details needed to actual write PLC code, such as permissives, alarms, totalizers, setpoints and their allowable ranges, sequences, and much more. Hammering out these details is crucial for a successful project.

Before the Project

The time to write a functional spec is at the very beginning of a project, before any programming begins. The functional spec is the standard that the system will be built and programmed to.  This clearly defines the scope of the project and sets the project up for success. It is much more efficient for all parties to discuss all of the functionality at one time, rather than leaving questions to be answered during the programming.

Once the functional spec is written, all parties will review the document and approve it before the next phase can begin.

During the Project

During the development phase, when the project is in process, the functional spec is referred to often throughout programming. The primary purpose of the functional spec is to explain to the programmers how the system needs to operate.  In programming, you need to be extremely specific.  This is where a great functional spec will shine. If details are left out, programmers will either need to call the end user (for seemingly trivial questions), creating delays, or make decisions on their own, which risks a system that does not work as the operators  or engineers require

Read more about what is included here

The functional spec serves as a checklist, which helps the project stay on time and on budget.  During the project, the programmers will also complete some “desk-testing” of the system to verify that it is operating as intended. This is good quality assurance programming behavior

The functional spec also allows the programmers to know when they are done and ready for extensive testing. Once everything in the functional spec has been completed, they are ready to move onto the next phase.

Next, formal testing begins. The purpose of internal testing and witnessed testing with the client is to make sure that everything works as laid out in the functional spec.  Therefore, by the end of the testing, the functional spec and the programming should be completely aligned. The functional spec then becomes a written dialog of the functionality of the system – in English instead of the programming language – and can become a pseudo user manual.

After the Project

As the project comes to a close and is ultimately completed, the functional spec is still a terrific resource to the end customer. The functional specification should be considered a living document; it should always kept up to date and maintained to serve as an accurate guide and representation to all parties of what programming lives within the PLC. It helps train new operators, guides future programming efforts, and is a guide for troubleshooting when issues arise.