Requirements documents don’t deserve their bad reputation

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

"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