Requirements Writing Style and Synonyms

A rose by any other name…

When we’re learning how to write in high school and college, we’re taught that synonyms make our writing more exciting. In fact, not using synonyms can make our prose clumsy and awkward.

When it comes to requirements, the last thing you want to do is use synonyms. Except sometimes.

Writing Stylish Requirements

One of the lesser appreciated rules of writing good requirements is to write requirements with good style.

Your writing style needs to take into account the fact that not all of the readers of your requirements will have English (or whatever language you write in) as their primary language. The readers may have as a primary language one that does not have the same idioms, constructs, and “common” terms as the language of the requirements. Those readers are already at a disadvantage, having to reverse-engineer colloquialisms, decode complex sentence structures, and look up the definitions of terms that they don’t know.

Even readers who share a common language [Great joke from Eddie Izzard: “Britain and America are two countries separated by a common language”] probably will not share the same idioms and colloquialisms.

Writing clearly and unambiguously requires that you use more formal language when writing requirements. Synonyms may make for better style when writing prose, however, they can confound your readers and increase the risk of misunderstanding when used in requirements documents

Avoid Synonyms

Synonyms introduce ambiguity into your requirements. Consider the following examples:

• The user will have added items to her shopping cart while browsing the website. When she is ready to purchase the items in her cart, she will click on the “cart” icon. All of the items in the basket must be priced with the most recent pricing rules.

Are you pricing the items in the basket, the cart, or the shopping cart? That may seem obvious to you, since most of us are familiar with the shopping cart metaphor in e-commerce transactions. What about the following?

• A round bit must not rotate within the head when the vice is adequately tightened.
• The vice will be tightened with a key measuring no more less than two inches in diameter.
• A moment of 10 inch-lbs applied to the chuck will be considered adequate for tightening.

If you don’t know that chuck and key are synonyms, you’re in trouble. If you don’t realize that the vice and the head can also be considered synonyms in this context, you are in more trouble. You should use the same terms throughout your requirements document, when referring to the same object or concept.

Except when you should use different terms for the same objects.

Embrace Synonyms

There are times, however, when synonyms can bring clarity to an otherwise confusing document. This effect is less powerful than introducing confusion, so when in doubt, don’t use synonyms.

Synonyms provide clarity when used in a particular context. If you sell cars, then you have a customer. Imagine you also provide financing (products) for your customers. In the context of negotiating a price for the car, the customer is a customer. In the context of negotiating an interest rate, the customer is also a borrower.

Validating the requirements for the lending process may be much easier when using the word “borrower” instead of “customer.” What you are striving for is clarity of language, and when interacting with stakeholders who have always used the term borrower, you can use that term in your documentation.

The key is to identify the synonym in the glossary of terms. You have to identify the synonym as being associated with both the equivalent term, and the context in which the synonym applies.

The customer at the car dealership can be the purchaser, the borrower, and the driver. It all depends on context. When you manage the synonyms within your glossary you can use the different terms. But you should only use them when they reduce ambiguity – not when they introduce it. Even with our example, the customer and the borrower might be different people – so make sure that the synonymous terms represent the same object, and not potentially different ones.