Breaking News

Thursday, January 13, 2011

Requirements Documentation: Will vs Shall

Recently, at work, while writing use cases, I was somewhat compelled(because everyone else was using "will", instead of "shall") to write requirements using "will" statements.

Though I never thought about its importance, I knew it is an important aspect when creating requirements document, especially if its an international project. And I must admit that today was the first time I actually thought of why I have always used shall statements in requirements? This aspect of requirements gathering was inherited from the company where I started writing the requirements.

As I research I found following interesting facts:

  1. This practice, using shall over will, is defined as best practice in RFC 2119 - standard set of best practices for communication.
  2. According to wiki, shall implies and obligation, while will implies intention or willingness.
  3. In English grammar, for second and third persons, will is declarative(willing), while shall is imperative(Obligation).

Example:
Intention: User will click on the start button. (Intends "willingness" - may do, or may not do)
Obligation: User shall click on the start button. (Intends a "must do")

The english language seems to be not really precise, unless you add or state very specifically what you mean in more words than people care to read. A good example between shall and will taken from here:
"Will" just indicates intention. You might say: "I will fix this bug" (you intend to)
"Shall" indicates obligation. You boss might say "You shall fix this bug" (it's an order)


Why its important?
It may not be important for those whose national language(not mother tongue) or major medium of communication is not English; but it may be important if you are dealing with an international project where, when used in contracts, may have severe legal implication; and probably, be challenged in the court of law.

And what should you do when you have a microscopic project timeline, and no time to discuss/argue?

Besides just following the instruction(yes, best thing - for the project success - is to follow the instructions), as a part of your responsibility you should "definitely", provide your feedback to the team/management; and provide with authentic sources to justify/backup your claim.

Before you enjoy, get that job done - highest priority and asap. (0:

1 comment:

  1. Another approach I like is to just use the present tense:

    "The program outputs 'bar' when the user clicks on the 'foo' button."

    This way the requirement document is correct when the implementation is done :)

    What about the fact that initially the requirement is not true? Just enter it as a "bug" :)

    BUG: "the program does NOT output 'bar' when the user inputs 'foo'"

    ReplyDelete

Designed By Published.. Blogger Templates