Requirements documents don’t deserve their bad reputation

Featured
11717 Views
6 Comments
8 Likes

"Requirements documents are a thing of the past because they don't accept change, and change is not only inevitable but often desirable."

"Word documents, wikis, etc., are all designed to manage blocks of text, not requirements, so they only work well to capture general reference information that is static over a period of years."

Requirements documents don’t deserve their bad reputation"Documents with designation like System Requirements Document or Software Requirements Specification are damaging to projects because they represent fixed sets of information and don't have any living relationships either to elements within the document or to elements outside the document. Change something in one document, and corresponding or resulting changes must be made manually in other documents. It is easy for the various documents to become outdated, disconnected and even contradictory.”

You have probably seen similar statements in whitepapers or sales materials. Arguments against requirements documentation are typically presented to build a business case for one of the following:

  • Requirements management tools that allow requirements to be individually captured and managed, with traceability to other elements like design and test items.

  • Solutions for creating visual models to replace textual requirements.

  • Training or tool for agile requirements that will “help you get rid of the BUFR (big upfront requirements document)”.

The problem with these statements is that they suffer from confirmation bias — the tendency people have to favor their beliefs or hypotheses. Yes, requirements documents are sometimes more difficult to maintain than more fluid models, especially if they are subject to rigid approval cycles, or stored in big documents instead of smaller pieces representing project modules, components, or releases. And yes, without a specialized tool for traceability you may need some extra steps in your process to ensure that changes in one artifact trigger updates in other affected artifacts. But the fact is, the exact same problems blamed on documents can happen with any tool or model used to capture requirements. If your process is too rigid, or makes it difficult to approve or track changes, then no matter how sophisticated the tool you’re using, the same problems will arise.

The most disappointing criticism, to me, comes from vendors who describe wikis as poor vehicles to capture requirements. I’ve been using wikis as a repository for requirements for years at various consulting clients, and a good wiki will allow you to organize requirements in ways that facilitate individual requirement approval, review, and traceability. If something changes, it’s very easy to follow the link to the corresponding design and test spaces to update them accordingly. There are multiple ways to ensure users are notified of changes in one artifact that may affect their deliverables. I really don’t see a difference in terms of the amount of work compared to running a report to find and fix “suspect links”, the standard process in some requirements management tools I’ve used in the past. Either way, you still need someone to manually review the “suspect” items to check if their content needs to change.

You’ll notice that many requirements management tools that claim that “requirements documents are obsolete” typically provide a feature to export requirements as CVS or text document (good wiki tools provide export functionality too). This is important because even though there’s value in being able to capture requirements individually to filter them, break them into tasks, etc., looking at requirements individually doesn’t help stakeholders see the forest for the trees. In order to have a full picture, it’s important to have requirements presented in context and in an organized fashion --ideally with the description of system functions augmented by visual models that identify complete system usages and detail the action flows for these usages.

Obviously some tools are better than others to create and maintain sets of requirements, reducing the amount of work for business analysts, and making the process less error-prone. A collaborative environment, in which project information is always up-to-date and available as the “one source of truth” (which, again, a wiki is capable of providing), dramatically increases the efficiency and effectiveness of delivery teams, compared to, say, static documents stored in a shared drive. But even though they may help organize, share and maintain requirements, specialized tools will not eliminate issues such as redundancy, contradiction and obsolescence.

At the core of a good requirements management system is a good business process, not a fancy tool. Such process needs to clearly define how changes will be submitted and approved, and how team members will be notified when a change affects downstream or upstream work. Depending on the tools in use, updates may require less or more manual steps, but the quality and productivity of the team doesn’t need to suffer because you don’t have the latest and coolest tool in the market.

No off-the-shelf solution can replace the right business process to enable the early discovery of misconceptions, overlooked requirements, logical defects and other issues that plague so many software projects. Commercially available software may help, but won’t prevent requirements from getting outdated or disconnected from reality, nor will it magically fix a rigid process that locks requirements early on and protects them against any future change. Each requirements management and visualization solution will have pros and cons, and there are plenty of open source and low-price, subscription-based tools that make it possible to promote good communication, common understanding and agreement among project stakeholders. For that reason, vendors should be placing their efforts into proving how their tools can make a real difference, rather than presenting their solutions as “the cure” for requirements problems whose root causes have nothing to with technology or feature set.

Author: Adriana Beal has 13 years of experience working on increasingly complex software development initiatives. During this period she has helped a diverse client base that includes IT, telecom, health care, and major U.S. financial institutions understand the real business problem and make better decisions about their internal and customer-facing applications. Adriana’s work currently focuses on executive-level consulting in ecommerce, mobile and web-based applications, as well as implementing performance measurement systems for business analysts via Beal Projects.


Article photo © CaliCirilo - Fotolia.com

Like this article:
  8 members liked this article
Featured
11717 Views
6 Comments
8 Likes

COMMENTS

adrianab posted on Tuesday, December 17, 2013 8:30 AM
Posting just to subscribe to the thread, as I learned this is the only way to be notified if someone leaves a comment.
ryanmilligan posted on Wednesday, January 1, 2014 11:50 PM
Excellent points in this article - I've been waiting for someone to take a stand of behalf of requirements documents. I've taken both the document (Word, etc.) approach as well as the tool (HP Quality Center, ClearQuest, etc.) approach, depending on what the project requests. Some of the newer tools are pretty nifty, but it truly doesn't matter if you don't have a process in place for making updates. Requirements kept in tools are just as prone to becoming stale and out of date if they are neglected as a solution evolves. In the end, it's all a matter of preference regarding ease of use, flexibility, and organization. Plus, technologies such as SharePoint have made collaborating on Word documents easier over the years.
adrianab posted on Thursday, January 2, 2014 10:31 AM
@Ryan

Thanks for adding your views, and for the compliment. Indeed, people like us, who have been exposed to various document- and tool-based approaches to capturing requirements, can attest to the fact that the process, more than the tool, is what keeps requirements statements relevant during the entire project, and even after the system is delivered.

BAs should take advantage of the capabilities available to help them create and manage requirements in a more efficient manner, and you bring a good example in SharePoint. I've used it a couple of years ago in my projects, and was surprised with how many of its useful capabilities were being ignored by other BAs -- features that could provide automated notification of changes, capture Q&A with stakeholders that would help with system documentation, and so on.
dphseven posted on Friday, January 31, 2014 8:44 AM
Adriana,

Just getting to your article after a busy start to the year.

I'm personally an anti-document type, but what you say is spot-on. It's easy to get wrapped up in the sales lit from platform vendors. But if you are implementing a tool as *the* solution to your bad process, lack of team experience, etc, you're bound to be disappointed.

My own experience is that the tools, as they exist today, tend to be more helpful to management and product managers. They don't provide any tangible benefit to their core users, the authoring BA. Some of the tools are starting to provide interesting features like requirements review checklists, wikis, etc. I hope this trend continues.

Any way, good article. It's good to see some counterpoint to the white papers out there.

best,
DPH
adrianab posted on Friday, January 31, 2014 9:04 AM
Hi, DPH,

Thanks for adding your view. You offer a good reminder: if you are going to implement a requirements tool, fix your process first. You won't know what tool will be more effective until you know what your to-be process looks like, and even a quality tool may disappoint if you wait to discuss the process later.

I'd only add that if a tool supports larger business objectives (for example, being helpful to management and product manager like you mentioned, or having other valid purposes), BAs should be supportive of using them. It does make sense for us to do things because they help the organization or a group of stakeholder, even if they don't benefit us directly. For example, creating various artifacts to represent requirements in different ways: UML diagrams for technical people used to them; other types of diagrams that are more intuitive for business users who don't want to learn UML; high-level powerpoint presentations summarizing the features included in a software requirements document, and son on. Sometimes it becomes boring for me to redo things in all these different formats, but if it helps drive consensus or ensure a common understanding between business and technical groups, then it's well worth the effort.
johnson.a.nick@gmail.com posted on Sunday, February 15, 2015 10:27 PM
Good article. I agree there is no substitute for process. Great tools and documentation is nothing without a solid process for managing.
Only registered users may post comments.











Copyright 2006-2020 by Modern Analyst Media LLC