Elements of Requirements Style
The goal of writing requirements is clear communication. Here are many tips for achieving that outcome.
Writing software requirements is hard! There’s no formulaic approach to it, and yet clarity is essential. High-quality requirements begin with proper grammar and spelling, well-constructed sentences, and a logical organization.
This article presents numerous style guidelines to keep in mind when writing functional requirements. However, I’m not a fan of arbitrary writing rules. Some I’ve heard are:
- A requirement may not contain the word and. And indicates the presence of two requirements, which must be separated.
- A requirement may not contain more than one sentence.
- A requirement may not contain more than 22 words.
Such simplistic rules are intended to help business analysts (BAs) write good requirements, but too often they aren’t good advice.
As you write your requirements, always remember your key objective: clear and effective communication among the project stakeholders.
I Shall Call This a Requirement
Shall is the traditional keyword for identifying a functional requirement. Functional requirements describe behaviors the system shall exhibit under certain circumstances or actions the system shall let the user take.
Some people object to the use of shall because it feels stilted. It’s not the way people normally talk, at least not outside English period-piece movies. True — but so what? Using a distinctive word like shall clearly distinguishes a requirement from other information in a specification.
Too many requirements documents use a random mix of verbs: shall, must, will, should, could, would, is recommended, is desirable, is requested, can, may, and might. People use many of these words interchangeably in casual conversation. The listener relies on context and the chance to ask for clarification to understand the speaker’s point. But this can become confusing in a document.
The reader is left to wonder if there’s a subtle but important distinction between these various keywords. Does must carry…