Writing Stylish Requirements

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

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.

Post navigation

3 thoughts on “Requirements Writing Style and Synonyms”

some “moments” are measured in units of time, (minutes, seconds, etc.) but not the moment mentioned in your article: “A moment of 10 foot-inches applied to the chuck.” This moment refers to a torque, which has units of [distance x force] such as foot-pounds or newton-meters, but not foot-inches which is a meaningless unit in this context. So don’t just stick with clear language, make sure it is also accurate.
Chuck, (A nickname for Charles, me, not the kind that holds a drill bit)

Hey Chuck, THANKS for pointing out the typo. I originally typed foot-lbs, then went back to edit it to inch-lbs (because 10 ft-lbs on a 1″ lever is pretty intense), and my brain apparently shut down in the middle of the edit. I guess it could have been worse, I could have had lb-lbs.

@sehlhorst on Twitter

Who Should Read Tyner Blain?

These articles are written primarily for product managers. Everyone trying to create great products can find something of use to them here. Hopefully they are helping you with thinking, doing, and learning. Welcome aboard!