A Call to Every BA: 8 Mistakes to Avoid in Writing Requirements Specification Documents

/

According to the Strategies for Project Recovery report by PM solutions which was based on 163 respondents, $74m invested in projects annually, are at risk of failure. The report identified one of the top 5 causes of project failures as unclear, non-prioritized, contradictory, ambiguous and imprecise requirements.

Sit back and relax. This is a long one.

Information like this is quite disconcerting, considering the fact that it is the responsibility of business analysts to elicit, manage and communicate requirements. As a first step in rising up to the call of producing high quality requirements and turning the tide of ICT projects, this post points out the tricky nature of requirements and mistakes that BAs can avoid when compiling Requirements Specification Documents.

According to the 1986 paper by Parnas & Clements, “A Rational Design Process: How and Why to Fake It”, designing software in a rational, error-free way from a “complete” Requirements Specification Document is like searching for the philosopher’s stone. I once wrote an article: Agile Software Development Methodology: Remedy For the Incomplete Requirements Specification Document, based on my experience, on how difficult or should I say impossible, it is to write a complete Requirements Specification Document.  

So, what exactly makes writing requirements so tricky? Here are 6 factors to consider:

  1. Stakeholders do not always know what they want and when they do, they’re unable to tell us everything they know. This can happen where a stakeholder assumes that the analyst already has information they don’t have, where the stakeholder hoards information, where the stakeholder is unable to put into words exactly what they want due to communication gaps or where the stakeholder is unable to anticipate everything he needs due to the simple fact that he is human.
  2. Even if we knew all the requirements to get started, additional but useful facts only become obvious after we have started the design work and in some cases, when the system is being tested. As we encounter new information or product defects, analysts often need to go back and refine the requirements while minimizing lost work.
  3. There are too many details surrounding the development of a system that humans are unable to comprehend. This is where bounded rationality comes in. Human beings, no matter how intelligent they are, are faced with 3 main constraints: a) Only limited and often unreliable information are available to develop requirements b) the human mind is limited in its capacity to process the available information c) Most projects are time-bound, thereby shortening the time it takes to fine-tune requirements
  4. External factors, over which we have no control, can cause requirements to change
  5. Even where concerns are separated, errors in stating or representing requirements can still be made since it is handled by humans
  6. We are often influenced by pre-conceived ideas and notions (from cases studies), which may cause us to misinterpret or misrepresent requirements along the line.

Bearing all these in mind, all we can do is try. We should still create Requirements Specifications Documents as if we had followed a rational process.

So, what exactly are Requirements Specification Documents?

A Requirements Specification Document outlines what the software is expected to do. Between business users and the analyst, an agreement must be reached on what actions users can perform and what responses they can expect to receive from the system. It serves as a contract between the analysts and the customers which specifies the “rules of engagement“ in using the software.

Why would you need one?

  • Requirements Specification Documents play a significant role in the design process and are used as a reference point for system design throughout the software development lifecycle. How would developers know what to develop without one?
  • It’s a document in which requirements are recorded and reviewed for approval – the scope of the project is explicitly contained in the Requirements Specification Document.
  • It prevents the need to make spontaneous decisions about requirements as the project evolves. Programmers should not be the ones deciding what is best for users
  • To avoid duplication and inconsistency. Programmers or stakeholders may ask the same questions repeatedly and receive inconsistent answers each time. Having a central point of reference will help to clarify grey areas throughout the duration of the project
  • The document forms the basis of arriving at an accurate estimate of the amount of time and resources needed to conclude a project
  • It provides insurance against personnel turnover. Requirements will not exist in one person’s head. Knowledge of user requirements can easily be transferred to other projects even when analysts or developers have left the team
  • Provides a basis for writing and developing test cases

On writing better Requirements Specification Documents, what is the way forward?

While there are no excellent ways of writing the RSD, there are some mistakes we can consciously avoid.

  1. Poor Organization
    Avoid poor organization by defining the structure of the RSD before you start writing. Each requirement should be defined in one section and one section only. 
  2. Confusing/Inconsistent Terminology
    Use a glossary containing the definition of all the terms used; this will ensure that all members of the team understand what the document is about.
  3. Boring Prose
    Don’t use plenty of words where you can use a picture or a formula. Also, repeating facts in different sections of the RSD increases the burden on the reader and causes inattentive reading which in turn, may lead to undiscovered errors. Repetition of requirements in various places on the document would require maintaining different sections of the document when changes need to be made. The resulting read should be detailed and precise but not boring.
  4. Myopia
    Requirement Specification Documents should be written clearly without assuming that readers have a prior understanding of the requirements or the domain. This would prevent misunderstanding further down the line. All assumptions should also be clearly stated and areas where information is not known or is likely to change should be highlighted.
  5. Solution-Bias
    Requirement Specification Documents should not describe solution ideas or contain any implementation details. They should describe only “what” the business needs and not “how” the needs will be implemented.
  6. Non-Verification of Requirements 
    Requirements should be verified with users again and again. Since requirements cannot be gathered all at once, they need to be evolved. The RSD should be continually reviewed whenever changes are made and updated whenever requirements are discovered.
  7. Bad Presentation 
    Presentation does matter.
  • Use descriptive titles
  • Use bullet points and short sentences to assist readers in staying focused.
  • Use the active voice in writing requirements
  • Use a table of contents so that readers can navigate bulky documents easily
  • Avoid the Russian nested doll effect – Requirements within requirements. Always break down parent requirements and never use “and/or” in your requirements documents – this would mean that several requirements have been nested together in one and can easily lead to confusion.

     8. Neglecting the acronym FUC4TM

         Requirements should be

  • Feasible
  • Unambiguous
  • Complete
  • Cohesive
  • Consistent
  • Correct
  • Testable and
  • Modifiable.

How else can Requirements Specifications Documents be improved?

Join the call and share your thoughts.