The Importance of a Project Specification Document
Much has been written on the subject of creating legal contracts, often including statements like, “Good contracts make for good clients,” and “Good contracts lead to good customer relationships.” Contracts are important. In addition to stating legal and financial requirements, contracts define what is to be done for the client. Just as important as contracts, proper specifications are needed to identify clearly how the contract requirements are to be satisfied.
We have written this to remind our peers about the importance of specifications to any engineering project, and to explain to any prospective clients that we know how to deliver what is expected. When we say, “We get it,” the functional specification is where “it” is defined.
A lot has also been written to give advice to project managers on how to run a project. This post is not intended to summarize such advice. We cannot do that properly as we are not project managers. Rather, we are engineers who have worked on various project teams and have some experiences to share.
Most of the projects we have worked on have benefited from good task definition provided in well-written specifications. Some projects, however, have had troubles caused by a lack of such definition. Many of those difficulties could have been avoided by writing and reviewing a functional specification to provide a clear and unambiguous description of exactly how a project’s technical requirements are to be met. (Sorry if that sounds repetitive or preachy, but by now you may have realized we feel strongly about this issue.)
In this discussion, the requirements for an operator display for a hypothetical project will be used to illustrate examples where needed.
A functional specification describes what the delivered system must do, similar to the project’s contract, but with much greater detail. It is the most important specification for any project (in our humble opinion). It may contain a process narrative or a sequence of operations. It may be augmented with I/O lists, interface specifications, logic sequence charts, recipe tables, process calculations, and even pseudo-code. Such details are sometimes provided in a separate detailed design specification, which is beyond the scope of this discussion.
For our display example, a functional specification may describe the significance of different colors, provide user login security levels, and enumerate the operator display screens, providing descriptions of each screen’s content.
The contract may include a requirement to “provide an operator display with graphical screens to be used by the operator to control the process.” Such a requirement must be expanded into details useful to screen developers at the beginning of the project. If developers were to proceed with only that general instruction, and no further definition, the operator display screens produced may differ significantly from those envisioned by the end-user. Ideally, definition is completed before development starts. (An exception to this is for prototyping, discussed below.)
The functional specification must be reviewed with the process owner, to ensure both the developer and the process owner agree on the system to be delivered, including the screens in our example. This is important to do before the development work has proceeded very far, but some preliminary development is needed for reference during initial discussions, such as prototype screens.
Any meeting, webinar, or phone call to review the functional specification should include not only the design or process engineers from the process owner’s company, but also the individual operators and technicians that will use the system. For our operator display example, such a review with the proper attendees would quickly identify a situation where a user’s red/green color blindness makes it difficult to distinguish between a green colored pump (to designate that it’s running) and one that is red. Review would also identify any confusion regarding the significance of the color red. Does red mean off or faulted? It’s best to identify and resolve both those issues before all 20 or so screens have been developed!
The last part about avoiding rework helps illustrate the financial consequences of skipping over the steps in a project’s development cycle involving a functional specification. Without an agreed set of marching orders for the developers, it is rather easy to work for several weeks developing various aspects of a system, such as the screens in our example, with content the process owner dislikes.
The thoughts expressed here are not new. But they are forgotten far too often, which is why we took the time to write this as a reminder for you today. This can also provide a document you may use tomorrow, or whenever you need backup in future discussions when someone tries to convince you that a functional specification is not needed, costs too much, has no value, or, well, the list of excuses could get quite long.
Producing a thorough, well-written functional specification for any project is easy to justify and risky to skip. Describing the need for such a document with a thorough review during initial talks with a process owner demonstrates your professionalism. It shows you have methods for avoiding difficulties while meeting the end-user’s needs. It provides a document that says, “Here is what we heard you ask for.” Plus it gives you the opportunity to ask, “Is this what you want us to do for you?”
This post was written by the control system engineering team at MAVERICK Technologies, a leading system integrator providing industrial automation, operational support and control systems engineering services in the manufacturing and process industries. MAVERICK delivers expertise and consulting in a wide variety of areas including industrial automation controls, distributed control systems, manufacturing execution systems, operational strategy, and business process optimization. The company provides a full range of automation and controls services – ranging from PID controller tuning and HMI programming to serving as a main automation contractor. Additionally MAVERICK offers industrial and technical staffing services, placing on-site automation, instrumentation and controls engineers.