The Community Blog for Business Analysts

Stephanie Famuyide
Stephanie Famuyide

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, 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.

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 to 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 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 just 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: 1) Only limited and often unreliable information are available to develop requirements 2) the human mind is limited in its capacity to process the available information 3) 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 lessons we’ve learnt, cases studies or from formal institutions), which may cause us to misrepresent requirements along the line.

Bearing all these in mind, all we can do is try. Parnas & Clements suggest that we should still create requirements specifications documents as if we had followed a rational process

So, what exactly are requirements specification documents?

In clear and simple terms, a requirements specification document outlines what the software is expected to do. Between the 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. This is only logical. It serves as a contract between the analysts and the customers.

Why would you need one?

  • Requirements 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 where requirements are recorded and reviewed for approval – the scope of the project is explicitly contained in the Requirements Specification Document.
  • It prevents making 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
  • A software requirements document aids accurate estimation of the amount of time and resources needed to conclude the project
  • It provides insurance against personnel turnover. Requirements will not exist in one person’s head and knowledge of user requirements can easily be transferred to other projects even when analysts or developers leave 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 requirements specification document, there are some mistakes we can consciously avoid.

  1. Poor Organization
    Avoid poor organization by defining the structure of the requirements specification document 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 in the requirements specification document; this will ensure that all the 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 documentation 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 also 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. This would prevent misunderstanding further down the line. All assumptions should also be clearly stated. Areas where information is not known or is likely to change should also be highlighted.
  5. Solution-Bias
    Requirement Specification Documents should not describe solution ideas or contain any implementation details. It should describe only “what” the business needs and not “how”.
  6. Requirements Verification
    Requirements should be verified with users again and again. Since requirements cannot be gathered all at once, they need to be evolved. The document should be continually reviewed whenever changes are made and updated whenever requirements are discovered.
  7. 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 the document 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. Remember 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. 

Stephanie Famuyide is a business analyst blogger that blogs about all things business analysis. Visit http://businessanalystlearnings.com where I provide practical tips you can apply on the job. 

This entry was published on Apr 04, 2013 / Stephanie Famuyide. Posted in Requirements Management and Communication (BABOK KA). Bookmark the Permalink or E-mail it to a friend.
Like this article:
  2 members liked this article

Related Articles

COMMENTS

Jay Esparza posted on Wednesday, April 17, 2013 3:33 PM
Very informative and a great read! Thanks for writing this for us.
Stephanie Famuyide posted on Thursday, April 18, 2013 12:48 PM
Hi Jay, thanks for the comment! I'm glad you found it useful.
srikanthba posted on Monday, June 24, 2013 3:13 AM
Thanks for really simple way to address the possible mistakes by Business Analyst.
Can you please elobrate on ' Requirement specification document must not have implementation details'. Usually we have functional specification document describing the Requirements, Implementation details, Key requirements , Usecases that list the implementation details.
Stephanie Famuyide posted on Friday, July 5, 2013 10:52 AM
Hi Srikanthba, thanks for your comment. Here's my 2 cents:

What the system will do is different from how the system will do it. The main role of business analysts is working with stakeholders to define exactly WHAT the business needs are and not the "HOW" of it. The "how" I referred to in this article includes implementation details such as algorithms, processing logic, input and output designs, to mention a few.

Including requirements in your functional specification document in the form of use cases, as an example, is definitely required to assist the development team in understanding what the user wants. Use cases typically illustrate system functionality and are not designed to contain the logic of their implementation.

Hope this helps.
Only registered users may post comments.


Blog Information

» What is the Community Blog and what are the Benefits of Contributing?

» Review our Blog Posting Guidelines.

» I am looking for the original Modern Analyst blog posts.



Modern Analyst Blog Latests

Jarett Hailes
Jarett Hailes
As we start a new year many of us will take the time to reflect on our accomplishments from 2012 and plan our goals for 2013. We can set small or large goals. goals that will be accomplished quickly or could take several years. For 2013, I think Business Analysts should look to go beyond our traditional boundaries and set audacious goals. Merriam-...
2 Responses
Howard Podeswa
Howard Podeswa
Recently, I was asked by the IIBA to present a talk at one of their chapter meetings. I am reprinting here my response to that invitation in the hope that it will begin a conversation with fellow EEPs and BAs about an area of great concern to the profession. Hi xx …. Regarding the IIBA talk, there is another issue that I am considering. It's p...
12 Responses
Adrian M.
Adrian M.
Continuing the ABC series for Business Analysts, Howard Podeswa created the next installment titled "BA ABCs: “C” is for Class Diagram" as an article rather than a blog post. You can find the article here: BA ABCs: “C” is for Class Diagram Here are the previous two posts: BA ABCs: “A” is for Activity Diagram BA ABCs: “B” is for BPMN
1 Responses
Featured Digital Library Resources 
Copyright 2006-2015 by Modern Analyst Media LLC