The Precision of Specification/Requirements Language

Chris Petrilli provides some excellent commentary on language and phrases used in specification and requirements documents. Over the course of my career producing specifications, requirements documents, project charters, etc. I have come to favor very direct and unambiguous prose so that the intent of the document is as crystal-clear as possible to those reading and utilizing them for further work.

As such, I often find myself reviewing similar documents for others, and I always red-flag prose that could lead (and often does) to misinterpretation or other ambiguities. I agree with Chris and not the specs he cites in his post about the use of SHOULD and SHOULD NOT in these works - the resulting downstream interpretations are too risky.

Other words that trip my bad-word-o-meter include MIGHT or MIGHT NOT. These tend to show up when authors speculate about a solution to a spec or requirement, instead of leaving that for a separate exercise. For example, a spec could read "...and provide a response to the requester within 3 seconds of the request. This feature might be implemented as..."

Oops. The writer asserts the specification (3-second response) then starts to opine on how to solve the issue. No, no, no.....

One set I didn't see in Chris' post or cited references that I'd like to mention as potentially problematic are WILL and WILL NOT. The issues I have with this pairing is that in the context of language, they have the potential of introducing ambiguity by describing a future state where terms like SHALL/SHALL NOT and MUST/MUST NOT leave no margin for incorrect interpretation - so in practice, I strongly favor the SHALL and MUST pairings.

A couple of suggestions for my readers: take some time to go back to the spec and requirements documents you have produced in the past and proof them for the types of ambiguities that Chris and I have discussed in our posts. Use a very critical eye, your natural biases toward your work aside, and see if you can find such 'holes of ambiguity' in your prose. I can still find quite a few in my own, particularly in my earlier works...:) Replace the ambiguous terms with what's been suggested and then read again to see if the revision provides more clarity of intent and what is expected out of the implementation. Then, start writing that way in your future works.

Finally, I'm very interested in how my readers in foreign countries approach these issues in their native languages. Leave a comment or e-mail me - I'd love to know.

Comments

[tanya]

In Russia the majority of lecturers,consultants and advisors of all the fields of sciences use very impersonal, formal and scientific language.Actually it's always just the description of the proccess, so they don't need to express modality much.That's the main difference between the way Russian and foreign educators work. Foreigners always give a lot of examples,some from their work and even private life,try to give a lot of practical advice, too many details.

Remembering the saying that we all like to know something new but don't like to be taught I try to express myself in the following way,"You are to do this and that..."

[Sandy Kemsley]

"Might" and "might not" are sometimes used in the same way as "may" and "may not" as discussed in Petrilli's post, that is, to denote optional features. In the context that you state, however, they are red flags: not because of the language, but because the person writing the requirements is also trying to design the system.

I've found separation of business requirements, functional specifications and technical specifications to be a difficult but essential part of the process so that you don't end up with a business analyst determining code, or a developer determining end-user functionality.