Engineering Enigmas: Unraveling Confusing Instructions
During the Second World War, the United States government attempted to release a memo for the blackout order of 1942 to hinder aerial bombers.
“Such preparations shall be made as will completely obscure all Federal Buildings and non-Federal buildings occupied by the Federal government during an air raid for any period of time from visibility by reason of internal or external illumination.”
If you can’t understand these instructions, don’t worry, it’s them, not you.
The United States President at the time, Franklin D. Roosevelt, took a simpler approach.
“Tell them,” Roosevelt had instructed, “that in buildings where they have to keep the work going to put something across the windows.”
Clarity does not come from excess but from the right amount of simplification. Roosevelt understood that very few would grasp the first draft of the blackout order. It was laborious to read and even more so to understand.
This convolution extends to requirements.
It is not uncommon for engineers to fall into the temptation of overcomplicating a requirement, blurring the lines between functional and non-functional, and introducing unnecessary layers of intricacy. The resulting clutter infiltrates the requirement documentation, slowing down the pace of the approval process and potentially leading to errors in later-stage development.
For example:
[REQ-NA1] While the Garage Door is Open, the Garage Door opener shall turn on the light while displaying the open status on the display screen and wait in open mode.
This requirement contains three different actions that must be designed, tested, and verified. You could break out the requirement into bullet points, which may help visually, but the requirement remains burdensome and complicated. Moreover, attempting to test this requirement would present a daunting task, fraught with inconclusive results and arduous verifications.
But the opposite problem can also occur.
Insufficiently detailed instructions leave readers perplexed and desiring further clarity.
Take for example the requirement “the system shall be robust.” A simple enough requirement but provides no real substance to the project.
A robust system is not a bad thing to want, something a client may commonly request. But “robust” is an elusive term. There is no metric; no specific results are tied to robustness.
This vagueness makes the requirement difficult to fulfill and even more difficult to test. It would leave the average reader as confused as the original blackout order of 1942.
Written requirements tend to fall on either end of the spectrum – too detailed or not detailed enough. And after a decade immersed in requirements, we’ve witnessed the opposition between overcomplication and oversimplification. Which often leaves us asking the question ‘Who wrote these requirements?’
The art of writing often presents an intriguing paradox: while writers have a clear understanding of the message they want to convey, expressing it precisely can prove to be a formidable challenge. The complexity lies in translating abstract thoughts and ideas into concrete words and sentences that effectively communicate the intended meaning.
It demands the ability to bridge the gap between the writer’s mind and the reader’s understanding.
It’s the same when writing requirements.
“I know I am a good writer. I write it, I read it, and I know what I mean. The purpose of writing requirements is not for me to understand. The purpose of writing requirements is for other people to understand.”
Jordan Kyriakidis, CEO and Co-Founder, QRA Corp
Requirement authors often overlook that their ultimate audience is another human. Despite the rigorous process of reviews, approvals, and last-minute edits, it is crucial to remember that real individuals will be reading and relying on these requirements.
We are entering a time where the written word becomes more important than ever because it is the official record as knowledge transitions from tacit to explicit.
So, what methods do we use?
We find inspiration for the solution in an Einstein quote: “Everything should be made as simple as possible, but not simpler.”
A lovely quote but a challenging task.
We recommend 3 main solutions.
- Atomic Requirements,
- EARS,
- And Rules.
The solutions proposed are simple methods you can integrate company-wide, no matter the size of the organization. They provide cognitive scaffolding for requirements authors, guiding them to improve their authoring technique as they write.
Atomic
Atomic Requirements are The International Council on Systems Engineering (INCOSE) standard for writing requirements and a great way to ensure your requirements remain simple.
They are defined as “a natural language statement that completely describes a single system function, feature, need or capability including all information, details, and characteristics.” This style of authoring ensures that the requirement focuses on only one system and one function, without skimping on the necessary details.
For more on the benefits of atomic requirements and how to write them check out our comprehensive guide with examples!
EARS
The Easy Approach to Requirements Syntax or EARS helps engineers and business analysts write natural language requirements. The syntax provides easy-to-use templates that allow requirement authors of any experience to create a well-formed, detailed requirement.
With minimal training needed and low barriers to adoption, EARS is a technique we strongly recommend. We have an entire resource hub, complete with templates and thorough explanations.
Our requirement analysis software, QVscribe, has integrated EARS into the requirement authoring process. Users can directly apply the appropriate EARS template while they write a requirement and receive instant feedback on the quality of that requirement. Interested? Try our QVscribe’s EARS template with a free trial of QVscribe.
Rules
INCOSE’s “The Guide for Writing Requirements,” is a comprehensive how-to. The in-depth document describes the foundational aspects of writing effective requirements using 41 rules.
Drawing inspiration from INCOSE’s rule set, QVscribe has 16 problem types, each guiding the quality of a requirement. Enabling authors to incorporate know-how without the unreasonable expectation of consulting 41 rules when authoring.
- Exclude Subjective Metrics
- Exclude Unneeded Infinitives
- Exclude Non-Specific Temporal Terms
- Exclude Vague Terms
- Include Imperatives
- Exclude Escape Clauses
- Exclude Open-Ended Clauses
- Exclude Unspecified or Generalized Metrics
- Exclude Excessive Continuances
- Ensure No Missing Directives
- Exclude Negative Imperatives
- Exclude Unneeded Rational
- Exclude Non-Specific Pronouns
- Exclude Multiple Imperatives
- Exclude Passive Voice
- Exclude Incomplete Sentences
QVscribe’s software automates the application guidance to your requirements, drawing your attention to instances of deviation as you write. The instant feedback trains authors to adhere to the INCOSE guide without conscious effort, increasing the ease and speed of authoring. When following this framework, authors habitually write better requirements quicker.
Correctly adopting these rules is another way to ensure your requirements balance complexity and simplicity, over and under-simplification.
If you’re interested to see if your requirements are following these rules, try a free demo of QVscribe.