• Seilevel Team

    Here’s the Team

    Welcome to our Seilevel Photo Op.

Why We Should All Stop Creating Requirements Documents

I know what you’re thinking–you’re reading the title of this blog and wondering what’s wrong with me.  Did I have a stroke?  Have I been spending too much time around cowboy developers?  Am I disconnected from what business analysts are actually doing?  Not at all.  Let me assure you that I am ok.  I am probably healthier than I have ever been. I am still working on projects, and I haven’t spent time around any cowboy coders for about two years now.  In fact, my project work over the past several years has led me to the conclusion that none of us, as business analysts, product managers, or requirements engineers should be producing requirements documents. Those artifacts that many of you and your business/technical stakeholders know and love–the MRD, BRD, SRS, Functional Spec–all need to die quickly.  Here’s why:

1. Requirements Documents are Unmanageable

Practically the only thing you can reliably manage in a requirements document is the document version, and maybe the change history.  But this is only because SharePoint and Word do this for you. There is no way you can use a requirements document–whether it be written in Word or captured in Excel–to manage traceability from business objectives, to features, to models, to model elements (e.g., Process Flow steps), to requirements, to business rules without an excessive amount of manual effort and pulling of hair/gnashing of teeth. The problem becomes exponentially worse as your project increases in complexity. If I change a step in a process flow, and all of my requirements are managed in Word, how do I find all the requirements that are related to that step in the process flow, and how can I be sure that I have caught them all? If my business objectives change, and I have multiple requirements documents, how can I determine which requirements are impacted? In the initial phases of a project, requirements should be changing constantly as we gather new information.  If you are agile, requirements are changing all the time (this is a good thing).   How can you manage changes if your information is scattered across several artifacts, with nothing to rely on but your memory and maybe a spreadsheet which you have to manually update?

2. The Distinction Between Different Types of Requirements Documents is Artificial

Organizations are really good at establishing processes for software development, with stage gates and deliverables for each gate. For example, during the initial phases of a project (sometimes called envisioning or “pre-planning”), product managers tend to produce a Project Charter or a Marketing Requirements Document (MRD). Planning phases tend to produce a Business Requirements Document (BRD), and design phases tend to produce a Functional Specification or System Requirements Specification (SRS). Each deliverable tends to repeat or rehash a lot of the same information. But generally speaking, organizations are really bad about managing this information and referring to it in a consistent manner. If I make an update to the MRD, and my BRD and SRS refer to something the MRD said, how will I know which documents to update and which updates to make? Furthermore, one project’s BRD might be another project’s SRS–the level of detail I capture in any given SRS is relative the level of detail I captured in the related BRD. The information in the SRS depends on and includes information in documents that were created earlier in the SDLC, so why do we produce completely separate documents?

3. Documents are Disposable

I feel like I can be brief with this point: I will give a hundred dollars to anyone who has gone back and read a BRD more than a year after a project is launched.  Shouldn’t a set of good requirements be reusable across multiple projects?  After all, you spent thousands or maybe millions of dollars to write your MRD, BRD, and SRS. If they sit on a dusty (virtual) shelf after project launch, how will you continue to gain value from them? How many times have you had “requirements deja vu”–begun a requirements document only to realize that you wrote almost the exact same requirements 3 years ago? Do you remember where that BRD is, and can you easily find the relevant requirements out of the thousands that you wrote previously to reuse?

Ok, I can’t really give each of you a hundred dollars, but you get the point.

4. Documents Make the Wrong Parties Responsible for Approving Requirements

How many times have we as business analysts been asked by our project managers, “So when are you going to get these documents approved?”  It’s perplexed me for years now why BAs have this ownership. Requirement approval should be owned by the project stakeholders, but if requirements are captured in a document, and the BA owns the document, then the BA, by a false implication owns the requirements approval. Every BA around the world experiences the frustration of sending countless emails to stakeholders, keeping track (usually in a spreadsheet) of which stakeholders they’ve contacted, which have reviewed, and which have signed off. As a former colleague of mine used to say:  “We have computers. Shouldn’t the computer be able to do this for us?” For stakeholders who haven’t signed off, we have to waste way more time than we should bugging them for their approval, and keeping track of what we need to change in order to gain their approval, rather than spending our time what we should be doing–updating requirements and controlling scope.

 

So, if all of these reasons point to why documents are bad, then why are we still using them? That’s a good question. I think many organizations on some level intuitively know probably just about everything above is true, but they are stuck inside of their current processes:  “We must create a BRD using this template because that’s what the project management office says we have to do. If we don’t, then we won’t be able to get the next round of funding.” This is ridiculous. What most project management offices  actually care about is that the project documentation contains certain information at a certain level of detail and that certain stakeholders sign off on it–or at least, that’s what they should care about.

But don’t fret– there are ways to accomplish this without traditional requirements documents. Stay tuned for a follow-up post on how.

13 Responses to Why We Should All Stop Creating Requirements Documents

  1. ITBurkeAlert April 11, 2014 at 5:49 pm #

    I love this…and am also greatly interested in the follow up…

  2. Scott April 15, 2014 at 7:22 am #

    So…what do you suggest instead?

  3. Mark A Lucas April 15, 2014 at 2:33 pm #

    I agree on these points, at least on a basic level, and have been trying to make this change in various organizations for over 20 years!
    1. One of the worst uses of a requirements document is to get consensus approval from ALL parties, including developers, testers, and management. What is needed is phased, and ownership based approval.
    ~~ The business stakeholders should approve their business-speke scope and general requirements, and approval of verification reference artifacts like business process models and rules. Epic-user stories or use-cases can be approved, as well as conceptual user interface and report models.
    We dont need to make them have to approve syntactically correct use-cases, user-stories, data models, process models, or final-draft UI designs.
    ~~ We should let management types approve scope, and prioritization of epic-stories/use-cases. They need to take ownership of what is Critical and time-sensitive to be delivered within the project timeline.

    2. Documents are clumsy tools of the past, and the clumsy way they are typically written (e.g. starting every statement with “the system shall…”) are leftovers from when large organizations needed to “stub-out” document sections, such as when using IBM’s mainframe work-processor systems from the 1970s.
    Documents should be left for Charters and Scope statements.

    3. Detailed requirements need to be partitioned into the correct format, just like architects and engineers do in the physical industries.
    Business rules should live in rules tables and object/data models.
    Business rules should drive TDD as user-story “acceptance-criteria” and/or user-case “negative paths”.
    Process flows should live in graphical process models.
    Detailed UI and report designs should live as interactive prototypes, that can be used to generate the skeltons of the code that actually generates the presentation layer objects and the control objects (services).

    4. Non-functional requirements can live as narrative, but in thier own format, not clumsily trying to fit them into use-cases or user-stories. A specification table or “punch list” usually is all that is needed.

    5. Model-based requirements should be the rule, not the exception. Business/requirements analysts should be entering business-based requirements into modeling tools, not writing huge narratives that the designers and developers then have to translate into models (such as in Visual Studio or other modeling tools).
    Commom modeling languages or standards such as UML and BPML should be status-qou tools used by Business/requirements analysts, *not considered a “new and innovative” technology or technique.

  4. Dmitry April 16, 2014 at 12:34 pm #

    I think one of the ways to address some of these issues is to use traceability tools (e.g. Traceability Matrix). It’s not a holy grail though.

  5. Larry Trudelle February 10, 2017 at 11:00 am #

    Love it!

    I have wasted so much time over the years filling in the blanks of template BRD/SRD because the company wants it done. Not because it adds value or leads to better solutions. People waste so much time focusing on the form (literally) rather than the function.

    The bigger the company the worse it is. I currently work at a big telecom where they have multiple versions of BRD’s and SRD’s, and info is copied from one to the other, and they want me to complete all of them, because that’s the company way – it’s unbelievable.

    Some of the best requirements I have ever seen were written by people other than BA’s or PM’s. Basically, just business people writing what they need and why they need, using simple language that makes sense. And everyone was able to understand what was needed.

  6. Thomas Lantos January 17, 2018 at 10:34 am #

    I don’t agree at all… Its true, not many organizations manage this well, clients not taking the responsibility for signing off etc. and that’s why the problems. But that’s no reason for not creating requirement documents. Requirement documents are still needed just like you need a blueprint for building a house.

  7. James Hulgan April 6, 2018 at 3:18 pm #

    Thanks, Thomas. I agree that doing away with documents in and of itself won’t resolve process/cultural issues, but I’ve found that shifting from a document-oriented approach to a tool/report-oriented approach helps plant the idea that requirements are always in flux rather than “correct” or “true” according to a certain document. If you can accomplish the same purpose of the requirements (i.e., working software, met business objectives) with documents as efficiently, by all means do it!

Leave a Reply

Your email address will not be published. Required fields are marked *