Are Your Requirements Documents Worth the Drive Space They Take Up?

Author: Adriana Beal

Many books and articles describe the characteristics of good requirements and offer templates for requirements documents, but as we all know, applying such knowledge in real-life projects requires more than looking at concepts and examples in a book. In a blog post for TechRepublic,”10 things you should know about hiring a business or systems analyst” (HT: Mark Jenkins), Justin James listed “the ability to document effectively” as one of the critical skills to look for in a BA, explaining:

“One of the biggest problems I see with some BAs and SAs is that you can talk to them and see that they know what is needed — but they just can’t get it out of their head and onto paper. I have seen too many process documents that were written by someone who couldn’t write things in a fashion that could be followed. One of my favorite examples was a flowchart showing a process. Entire sections were completely orphaned (no way to get to them) and none of the “exit conditions” was reachable. Needless to say, this document wasn’t worth the drive space it took up.

The unfortunate consequences of poor requirements documentation

The problems arising from unclear, incomplete or conflicting requirements can significantly increase the risk of a software project not fulfilling its mission. Common issues that can result from poorly documented requirements include:

  • Delays and cost overruns caused by inability to get sign-off from stakeholders who don’t feel comfortable approving a set of requirements they aren’t sure reflects the real business needs.
  • Costly rework caused by having the development team implement the wrong functionality, which may also impact the on time delivery of the software product.
  • Users being unable to use an important function of the system after tests based on incomplete requirements deemed the product  “fit for use.”

Do your requirements documents elicit this type of reaction?

Below are signs that the BA isn’t effectively communicating requirements (taken from a real project implementing a workflow used to approve new pieces of content to be published to a Web portal):

  • A business stakeholder tells the BA, “I read the entire SRS. Most of the requirements made sense to me, but I had a hard time following the part about a request being submitted to an approver when we are following the 2-step approval process instead of the 1-step process.”
  • A tester says she is having a hard time writing testing scenarios for the various status that a piece of content submitted for approval may have, from pending to approved, saying that she found a series of requirements about status changes sprinkled throughout the SRS but couldn’t tell whether there were any missing scenarios.
  • A developer keeps sending questions to the BA to clarify what seem to be conflicting requirements, or missing requirements (for example, the document has a requirement explaining that content can be approved or rejected, and another informing what to do when a piece of content is approved, but nothing defining what to do when the content is rejected).

How to avoid ill-fitting requirements documentation – 4 simple steps

  1. Read good books about requirements (such as Karl Wiegers’ Software Requirements Third Edition, which provides excellent insight into what causes requirements defects and how to avoid them).
  2. When you distribute a draft of a requirements document, or perform a walk-through session, see if there are any parts of your document that are generating questions. Then, after rewriting the textual requirements as needed, try to identify analysis models that would be appropriate to represent that portion of the requirements. Draw one or more models and include them in your next version of the document to see if it increases understanding.
  3. Don’t just blindly follow standards of documentation that may exist in your organization. This article about a new Forrest Research report contains a good advice: take a step back and reassess the value that your documentation is producing. If you are just following prescribed methods and filling out text-heavy templates, there is a huge risk that you’re wasting time with excessive or inappropriate documentation that doesn’t necessarily add value to the project.
  4. Adjust the level of abstraction and detail of your requirements documents to the particular needs of your project and audience, and don’t forget include appropriate diagrams and models to provide additional context to the textual requirements you write.

I have written very few requirements documents that did not include visual models to improve understanding, but if you looked at the history of requirements packages I’ve produced in the past 10 years, you would see very little similarity in terms of format and visual representations that were used. Depending on the circumstances, I have successfully used storyboards, wireframes, fact models, data flow diagrams, and various ad hoc representations to augment the written communication. So this is probably the best advice I can give to BAs looking for opportunities to improve their requirements documentation skills:

Don’t fall into the trap of thinking that you can just fill out your company’s one-size-fits-all SRS template, or a reuse a template you found on the Internet. Think about the audience that will read your requirements, and negotiate with them the documents that need to be created, in what levels of abstraction and detail, and at what points of the project.

The richer the set of techniques to express requirements you become familiar with, the higher the odds that your documentation will tell the right story, generating an identical understanding among business and technical constituents of what needs to be built.

 

Free Training - Quick Start to Success

(Stop the frustration and earn the respect
you deserve as a business analyst.)

Click here to learn more

By signing up, you agree to our Privacy Policy.

Comments

  1. Hi, Isabella, thank you for your comment.

    As an IT business consultant, I frequently see the type of problem you describe — fortunately in your case people realized that there is no one-size-fits-all solution to requirements documentation, and made the necessary adjustments.

    Re: “Isn’t that a task for a BA to help stratify how projects are to be conducted in your workplace?”, I’m not sure I completely understand the context of your question. For what it is worth, in many of the organizations I’ve worked for, BAs do not help define the software development life cycle, project methodology, and so on. However, they should definitely be providing suggestions and recommendations when they see that the prescribed methods are not working — specially regarding the requirements process, and the type of deliverable that makes sense (or not) to produce for their stakeholders.

  2. Isabella says

    Hello,
    the company I work for has developed a framework for IT projects (and others) with a set of prescribed procedures and work products all project managers need to abide by. Yes, there are reviews to check if they do, it’s all part of the process. It has led to a “documentation overkill”. After some time, they got smart, and discerned by project size and project intention. And it is now a necessity that a project be tailored with the help of an expert at the company’s method. This expert helps to define which work products are needed, and assists in fitting the project plan. Now that there is project tailoring the passing rate at the reviews has increased significantly. The document quality is up, knowledge harvesting and re-use improved.
    Isn’t that a task for a BA to help stratify how projects are to be conducted in your workplace?

    Regards,
    Isabella

  3. Alicia, indeed, wireframes and other visual representations are not meant to replace textual requirements, but rather augment them. Finding the right combination of text and visuals to properly communicate requirements and eliminate all potential ambiguity that can be introduced when using natural language is what makes a business analyst a great requirements communicator.

  4. Alicia B. says

    While I do think mockups like wireframes or simulation, at the end of the day those only prove to be helpful for developers but when it comes to project managers they need to know more than just what it looks like but what it can do when an action is taken. I’ve been working to find a nice balance between mockup and text but at the end of the day our requirements end up heavy on text due to conditions and other factors that have to be communicated. Honestly when writing requirements you need both but one is never going to totally satisfy everyone without the other piece.

  5. @David: I’ve written some functional specifications that merely created/changed business logic and/or internal system calculations. In these cases, flow charts or UI mockups were not applicable, as no changes happened to the process, classes, activities, system states, or user interface.

    I can only hope that even without images you and other visual people would have found these requirements easy to understand ;-).

  6. David Smith says

    “I have written very few requirements documents that did not include visual models to improve understanding” – I am most definitely a ‘pictures person’ and I would think (without looking) that all my Functional Specifications have included flow charts, process models, User Interface mock-ups etc etc, as appropriate. A picture paints a thousand words. 🙂

  7. @David: Yes, excessive preoccupation with consistency does not add value. Like you, while working for a consulting firm I tried to create a collection of templates with the understanding that BAs should pick and choose which one(s) worked best under their circumstances (and even so, as a starting point, with the freedom to adapt, removing and adding sections as needed, because each project is unique, and attempting to fit all projects into the same mold is not a good idea).

  8. Great quote – “Depending on the circumstances, I have successfully used storyboards, wireframes, fact models, data flow diagrams, and various ad hoc representations to augment the written communication.”

    I sometimes fear that in striving for quality, we focus so much on consistency of approach that the medium becomes more important than the message. I would like my organisation (a niche BA consulting firm) to create a culture where templates become like toolboxes and the role of the experienced BA is choose the right tool – not just work through every single one.

  9. @Nik: thanks for the reference to Jim Clemmer — regardless of him being the quote’s author, I found his website and will bookmark it so later I can explore his ideas about measurement and feedback ;-).

    I’m glad you, like Laura and I, don’t like the idea of blindly following existing templates. Indeed, templates are useful, as they serve as a type of “checklist” to make sure you didn’t forget to add important things such as interface requirements, performance requirements, and other items that could be easily forgotten by stakeholders and BAs. But like you said, the primary focus is to make sure the requirements are properly communicated to the audiences who need to understand either to approve or to implement them. Templates should be looked as a reference and starting point, not an inflexible standard that every project has to adhere to.

  10. Nik Gebhard says

    Adriana, this is a very interesting article.

    I’ve often challenged the way analysts blindly fill out templates with little or no tailoring. I believe in ‘getting the message across’ rather than following prescribed templates to the n-th degree. Don’t get me wrong, this doesn’t mean that I think templates should be negated altogether, but I do believe that more focus should be attributed to the target audience.

    When using visual models to get messages across, there is always room for innovation and adaptability – rather than following strict UML rules. Ultimately, the audience/stakeholders need to understand and be on the same page.

    (I think the author of the quote above is ‘Jim Clemmer’.

  11. Nice quote, Curtis (I too wish I knew the author :-).

    Indeed, visuals are typically crucial to properly communicate requirements. It always surprises me to see a lengthy description of a system behavior that could be so much easier explained with a diagram or wireframe! Just text is never as good as textual requirements accompanied by visual models.

  12. Curtis Michelson says

    Adriana, I very much appreciate your comment:

    “I have written very few requirements documents that did not include visual models to improve understanding,”

    I’m often dumbstruck with how under utilized is one of the most highly adapted parts of our anatomy – the brain’s visual cortex.

    What the eye/brain has been able to take in at a glance, for millenia, whether that’s the location of prey in the savannah, or the arrangement of crops in a field, or armies moving on a battlefield, we have tried to replace or enhance with the written word. Word (the literal program MS Word, and the actual lexigraphic capability itself) are very, very late additions to the human’s mental repertoire. We take in words, at most, a sentence at a time, and that is excellent for certain purposes, where precision is required.

    But precision only vets value when context is there. And context comes from “seeing” the whole field – whether that’s the savannah, the battlefield, or the complex business process/case that is being ascertained and mined for value.

    Or better and more succinctly put, by someone who I wish could attribute it to, but the author is unknown:

    “a rough measure of the right thing is better than a precise measure of the wrong thing”

Before you go, would you like to receive our absolutely FREE workshop?

(No formal experience required.)

21689
21690

Quick Start to Success
as a Business Analyst

By signing up, you agree to our Privacy Policy.