ArgonDigital recently received an email from one of our clients seeking advice on the use of active voice when writing requirements.  The email read as follows:

“In an academic paper I often use as reference, there are a number of requirements listed which are written using passive voice.  For example: 

“If this side is active and the mode annunciations are off, the mode annunciations shall be turned on when the onside FD is turned on.”

I would like to rewrite this requirement so that it is stated using an active voice; however, there are three areas that are to be addressed in the single statement ( the “onside FD”, the “mode annunciations”, and “this side”) making a rewrite to active voice all the more challenging.  Here’s my first try:

“If this side is active and the mode annunciations are off, the mode annunciations shall turn on when the onside FD is turned on.”

If you have some advice on an alternative rewrite so that the above is active voice per best practices, I’d appreciate it!”

ArgonDigital response

The requirement cited above appears to be a control system requirement.  That said, the format/template for control system requirements is as follows:

[From:  Alistair Mavin, Philip Wilkinson: BIG EARS (The Return of “Easy Approach to Requirements Syntax”, 2010, 18th IEEE International Requirements Engineering Conference, Sydney, Australis, September 27 – October 1]

Ubiquitous requirements:

The <system name> shall <system response>.
Example:  The control system shall prevent the Engine from reaching an Overspeed state.

Event-driven requirements:

WHEN <optional preconditions/trigger> the <system name> shall <system response>.  Example: WHEN Continuous_Ignition is commanded by the Aircraft, the Control_System shall switch Continuous_Ignition to ON.

Unwanted behaviours:

IF <optional preconditions/trigger>, THEN the <system name> shall <system response>.  Example:  IF the Computed_Airspeed Fault_Flag is set to True, THEN the Control_System shall use Modelled_Airspeed.

State-driven requirements

WHILE <in a specific state> the <system name> shall <system response>.
Example:  WHILE the Aircraft is In-Flight, the Control_System shall maintain Engine_Fuel_Flow greater than or equal to  XX lbs/sec.

Note that in each case the word before the “shall” is the System which is performing the action, NOT an object of the action.  In addition, it is good practice to make clear the terms used in a requirement are defined.  The Continuous_Ignition, Control_System, ON,  Computed_Airspeed, Modeled_Airspeed, Engine_Fuel_Flow, Aircraft, In-flight are all terms that need to be defined in a data dictionary or glossary and made part of the Project ontology.  All terms need to be defined and used consistently throughout your requirement set, design, an documentation.

The rewrite proposed by the client is still passive in that it is the system that performs the action (turn the Mode Annunciations On) — the Mode Annunciations don’t turn themselves on as written.

It is also important to clearly denote logical conditions so as to not confuse the reader in thinking the requirement contains multiple thoughts.

In addition, it is not good practice to include both an IF clause and a WHEN clause in the same requirement statement.  Per your example, the WHEN is just another condition thus it can be included in the IF clause.

That said, I would rewrite the example requirement as such:

“IF [This_Side is ACTIVE AND the Mode_Annunciations are OFF AND the Onside_FD is ON], the System shall turn the Mode_Annunciations ON.”

Thus this requirement is easily interpreted to say:

“If the logical condition is True, turn the Mode_Annunciations ON.

Note: the above example assumes that This_Side, Mode_Annunciations, Onside_FD, and System are defined in the project glossary or data dictionary.  Also, ON, OFF, ACTIVE are defined states.

Another issue I have with the example requirement is that I do not know at which level of the architecture the requirement applies (system, subsystem, module, etc.).  If a subsystem or module requirement, then replace “System” with the name of the subsystem or module that is performing the action.  Moreover, if the requirement is a subsystem or module level requirement, then there needs to be a parent system requirement that deals with the overall need to display mode annunciations.  A very common error is to include lower level requirements at the system level and never communicate the real system “what” requirement.

I have found that there is a problem common to many academic papers…they often cite requirements without stating the context, level, and rationale associated with the requirement.  To address this problem, we encourage everyone to include rationale with each requirement to clearly communicate why the requirement is needed and its intent.

In closing, all requirements need to be written in the active voice “The <System> Shall ….”

For more information on this topic, read our blog “Use of Passive Voice When Writing Requirements”

As with all our blog posts, your comments on this topic are welcome.

I you have any other questions, feel free to ask your question on our “Ask the Experts” page and we will do our best to provide a timely response.