What’s Included in a Functional Spec?

functional spec document on table with hand highlighting text

A functional specification, or operational spec, is a document that outlines all aspects of a project’s programming requirements. It is essentially the guide that directs the programmers on how the system is supposed to function, providing value before, during and after the project.  To truly be effective, the functional spec needs to be extremely specific; no detail should be overlooked. Here are some key features and questions that we consider while writing a functional spec.

Device Level/Group Level/System Level Specifics

The functionality of each device and how it works with other devices should be explored.  For the following questions, start at the device level. Once that has been complete for each device, group devices that work together and analyze the questions again. Finally, bring the whole system together and verify that nothing has been missed.

  • When and how will this operate?
  • What alarms are necessary?
  • What SCADA information needs to be collected?

Communication

Often times, programmers are not only responsible for communication within their own system but with neighboring systems as well.

  • What devices need to communicate to each other?
  • Are there are other networks (besides the system level network) that need to be interfaced with?
    • What will the other networks control and what information will they need?
    • How will that communication be structured?
    • How will communication be initiated?

Inputs and Outputs

It is important to review the I/O and make sure that nothing has been missed, and that all dual functionalities have been noted.

  • Have all of the inputs been called out?
  • Has each input description included what it will control/how it will be used?
  • Have all of the outputs been called out?
  • Has each output description included how it will behave?

Calculations

Most systems run not only on inputs, but require some sort of calculation to remain functional and/or to gather important data.

  • What kind of calculations (process values/totalizers/runtimes/etc.) need to be programmed?
  • When will the data for the calculations be captured?
  • How often will the calculations be used?

User Interfaces

User interfaces are often what the end customer will interact with the most, so it is important to outline the details early on to ensure their preferences are captured.

  • What commands will be generated from the user interface?
  • What information needs to be displayed?
  • What setpoints need to be configured and controlled?
  • In the event of multiple user interfaces, what responsibilities are assigned to each interface?

Edge Cases

Edge cases explain how the system will function and recover from non-regular production.

  • How will the system recover from a supply (power/pneumatic/hydraulic/etc.) failure?
  • What steps need to be taken to ensure that stored values are not lost during a power outage?
  • What happens when communications are interrupted or non-functional?
  • What happens when the devices start to malfunction?

The more information listed in the functional spec, the fewer questions that will arise in the process. Remember, the details in the functional spec not only benefit the programmers, but the end customer as well. The more time spent up-front during the creation of the functional spec to review and explain the requirements of the system, the more closely aligned the final product will be to the end customer’s needs.