Requirements Analysis: Weasel words, weak expressions

The Short Story

While writing requirements texts (imperative sentences like "The SW shall etc."), as part of the analysis team, weasel words and weak expressions have to be avoided at all times. Automatic spell checking scripts can be devised to ensure that, prior to peer review, all these expressions are removed.

What are weasel words?
https://en.wikipedia.org/wiki/Weasel_word

Quoting:
"A 2009 study of Wikipedia found that most weasel words in it could be divided into three main categories:

1. Numerically vague expressions (for example, "some people", "experts", "many")
2. Use of the passive voice to avoid specifying an authority (for example, "it is said")
3. Adverbs that weaken (for example, "often", "probably")

Other forms of weasel words may include these:

• Non sequitur statements
• Use of vague or ambiguous euphemisms
• Use of grammatical devices such as qualifiers and the subjunctive mood
• Glittering or vague generalizations"

Remember: ambiguity is one of our major enemies when doing requirements analysis. Whatever gets approved will have to be implemented by the development team and tests will have to be written against it (by the test analysts). A requirement using weak expressions is failing the S criteria in the SMART quality attributes all requirements should have.

Books on Requirements?

For everything in life, there's a book. I even found some book for good friends of mine who ride the bicycle (that went something like "how to not ruin your sex life riding bikes"). Unfortunately a search for it in the Amazon store today does not yield results.

And then, there are good books on writing good requirements.

Some of them are pretty much old but they are still good books on the subject (this is an "old" art):

• https://www.amazon.co.uk/Mastering-Requirements-Process-Suzanne-Robertson/dp/0201360462/ref=sr_1_2?s=books&ie=UTF8
• https://www.amazon.co.uk/Mastering-Requirements-Process-2nd-second/dp/B008IT2WJW/ref=sr_1_3 (the 2nd Edition)
• https://www.amazon.co.uk/Managing-Software-Requirements-Approach-Technology/dp/0201615932/ref=sr_1_4?s=books&ie=UTF8
• https://www.amazon.co.uk/Managing-Software-Requirements-Addison-Wesley-Technology/dp/032112247X/ref=sr_1_5?s=books&ie=UTF8
• Writing Better Requirements: Amazon.co.uk: Ian Alexander, Richard Stevens: 9780321131638: Books

PS: Some classical papers on requirements:

• http://homepages.laas.fr/kader/Hooks.pdf

• http://www.win.tue.nl/~wstomv/edu/2ip30/references/smart-requirements.pdf

Additional references (sources for the INTERNAL QMS ENG02 Process) 

The main conceptual references for the process description, back in 2003, were:

Guide to the user requirements definition phase, ESA PSS-05-02 Issue 1 Revision 1 (1995).

Guide to the software requirements definition phase, ESA PSS-05-03 Issue 1 Revision 1 (1995).

Space engineering – Software, ESA ECSS-E-40B Draft 1 (2002)

Some additional references used were:

Managing Software Requirements: a unified approach, Dean Leffingwell, Don Widrig, 2000, Addison-Wesley

Mastering the Requirements Process, Suzanne and James Robertson, 1999, Addison-Wesley

Modelling for requirement engineering, Dr. Eric Conquet, 2002, ESA / ESTEC TOS- EME

Specifying Good Requirements, Donald Firesmith, in Journal of Object Technology, vol. 2, no. 4, July-August 2003, pp. 77-87. http://www.jot.fm/issues/issue_2003_07/column7

@2017-11, additional sources for QMS PCS. 

Paper: Writing good requirements

There are full courses, papers and entire books on the subject.
It is indeed important to get requirements right (either from the customer or to be able to gather them properly from the customer).

Here's an interesting (old) paper on the subject:
http://homepages.laas.fr/kader/Hooks.pdf

Quoting:
"Abstract. The primary reason that people write poor requirements is that they have had
no training or experience in writing good requirements. This paper will address what
makes a good requirement. It will cover some of the most common problems that are
encountered in writing requirements and then describe how to avoid them. It also
includes examples of problem requirements and how to correct them.
(...)
Published in the Proceedings of the Third International Symposium of the NCOSE - Volume 2, 1993. Prepared by the Requirements Working Group of the International Council on Systems Engineering, for information purposes only. Not an official position of INCOSE."

SMART requirements

It is always interesting to have some kind of quality measure to check the quality of the work we are producing at a certain phase in the waterfall model.

For requirements, each requirement must respect the SMART quality attributes. Here are 2 very good sources explaining the acronym:

• http://www.win.tue.nl/~wstomv/edu/2ip30/references/smart-requirements.pdf (an old but still up to date paper on the subject)
• http://www.iibacolumbus.org/download/chapter_meetings/chapter_meetings_2013/01-09-2013_Kate_Gwynne.pdf (an IBM presentation on the subject).

The "5 lines summary" lies here (Source: ITGM):  

Software Requirements must have some characteristics to fulfill their goals.The most known is that they must be S.M.A.R.T.:  

Specific: A requirement must say exactly what is required (and shall not use weasel words).
Measurable: is it possible, once the system has been constructed, to verify that this requirement has been met ?
Attainable: is it possible, physically, for the system to exhibit that requirement under the given conditions?
Realisable : is it possible to achieve this requirement given what is known about the constraints under which the system and the project must be developed?
Traceable : is the ability to trace (forwards and backwards) a requirement from its conception through its specification to its subsequent design, implementation and test?

PS. Another classification that sometimes is applied to requirements is the MoSCoW requirements prioritization method.