DIDO Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 4.1.7 Specifying Requirements ======
[[dido:public:ra:1.4_req:00_aboutreq | Return to About Requirements]]

[[dido:public:ra:xapend:xapend.a_glossary:r:requirement|Requirements]] are captured in many ways. In the government realm, this is usually done through codification into laws, regulations and contracts including [[dido:public:ra:xapend:xapend.a_glossary:p:performancespec | Performance]] and [[dido:public:ra:xapend:xapend.a_glossary:c:conformancespecification | Conformance Specification]]. In the corporate realm, it often comes in the form of [[dido:public:ra:1.3_gov:1_legaldocs:1_charter | Charters]], [[dido:public:ra:1.3_gov:1_legaldocs:2_bylaws | Bylaws]] and [[dido:public:ra:1.3_gov:1_legaldocs:3_pp | Policies and Procedures (P&P) ]] and contracts with other entities (see above).

Regardless of where the requirements are captured or by what organizations, they can in general be considered governing statements. The following are some guidance on how to write healthy governing statements and consequently also requirements. 

A [[dido:public:ra:xapend:xapend.a_glossary:g:governance]] Statement based on an __Engineering Governance__ Model developed at US Navy SPAWAR((
Stavros, Robert W. and
Albrant, Jeremiah;
__Engineering Governance__,
SPAWAR,
October 9, 2007,
)) is defined as atomic, succinct, absolute and definitive in nature. It contains specific instructions which can be validated through observation, measurement or testing.
  * **Atomic** - A Governance Statement only addresses a single topic. Indicators of non-atomic guidance are use of highly complex sentences, multiple sentences or conjunctions such as and, or, etc.
  * **Succinct** - A Governance Statement are short and to the point. The definition of terms or caveats that explain when a statement is applicable are not acceptable as part of the Governance Statement. Indicators of non-succinct statements are the use of words or expressions such as: consider, when possible, if, etc. 
  * **Absolute** - A Governance Statement is evaluatable with one or more non-subjective questions. Indicators of non-absolute statements are those which are subject to the interpretation of the evaluator. For example, “All menus must be user-friendly". No one produces menu's that they feel are user hostile.
  * **Definitive** - A Governance Statement is precisely worded and explicit in nature. Their words, terms and expressions need to be defined and not subject to interpretation. Indicators of non-definitive guidance are words that are not intuitively obvious to an outside reader. Some words that are examples of non-explicit words are: object, service and function. 

Another issue or controversy with specifying requirements is how the statements use imperatives originally defined in [[dido:public:ra:xapend:xapend.b_stds:tech:ietf:2119]], words like:

  * [[dido:public:ra:xapend:xapend.a_glossary:s:shall_req]]
  * [[dido:public:ra:xapend:xapend.a_glossary:m:must_req]]
  * [[dido:public:ra:xapend:xapend.a_glossary:w:will_req]]
  * [[dido:public:ra:xapend:xapend.a_glossary:s:should_req]]

A major sticking point is the use of the word **Shall**((
PlainLanguage.gov,
__Shall and Must__,
Accessed 5 March 2021,
[[https://www.plainlanguage.gov/guidelines/conversational/shall-and-must/]]
)) which basically claims:
  * lawyers regularly misuse it to mean something other than “has a duty to.” It has become so corrupted by misuse that it has no firm meaning.
  * it breeds litigation. There are 76 pages in “Words and Phrases” (a legal reference) that summarize hundreds of cases interpreting “shall.”
  * nobody uses “shall” in common speech. It’s one more example of unnecessary lawyer talk. Nobody says, “You shall finish the project in a week.”

However, the counterargument is that **//Must should not be use because no one has defined how must is different from shall. Also, shall has held up in court, must has not.//** ((
Wheatcraft, Lou,
Requirement Experts,
9 October 2021,
Accessed 5 March 2021,
[[https://reqexperts.com/2012/10/09/using-the-correct-terms-shall-will-should/]]
)). So, whether you should use **Shall** or **Must** is a matter for the [[dido:public:ra:xapend:xapend.a_glossary:c:coi]] to determine, and it should be consistent. 

There is an excellent reference in __How to Write and Exceptionally Clear Requirements Document__((
QRA, 
__How to Write and Exceptionally Clear Requirements Document__,
Accessed 5 March 2021,
[[https://qracorp.com/write-clear-requirements-document/#elementor-toc__heading-anchor-1]]
)).

<color darkred><todo @char>Review </todo></color>

/**=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
/* To add a discussion page to this page, comment out the line that says 
  ~~DISCUSSION:off~~
*/
~~DISCUSSION:on|Outstanding Issues~~
~~DISCUSSION:off~~
DIDO Wiki

User Tools

Site Tools

Page Tools
