The typical requirements document is a long, sprawling piece of literature. Within it, one might find a title page, table of contents, change history, complex headers and footers, legalese, confidentiality notices, and, if you're lucky, maybe even requirements.
Its length is probably, primarily due to the fact that it tries to be everything to everybody. But, the problem is that this big freaking document isn't read entirely by any single person, except perhaps by the person who wrote it in the first place.
Every company refers to these documents as something different: BRDs, PRDs, BPDs, DRDs, SRSs, FRDs... or any other number of acronyms that people have forgotten the meaning of. OMG! To complicate matters, each department, project team... heck, person, uses their own template; so, one BRD does not necessarily equal another. But, who can blame the people that write these things? There are deadlines to be met, and all templates do not accommodate the needs of the many. Adjustments are made.
But luckily, from where I sit, I believe that the typical, mega-honking requirements document is nearing its death. And the good news is that this eventuality is closer than most people think. Don't believe me? We have actually witnessed this happening at some of the more progressive companies that we've worked with.
Let's walk through the reasons why I think these documents exist, and the problems that lie within.
To Communicate
In my mind, your primary job - whether you call yourself a "business analyst", "requirements manager", "product manager", or whatever - is to translate needs from one level of detail, to another. Thus, to be an effective business analyst, you must be an effective translator. This means that you must be able to talk the language of the business, and then effectively analyze and formalize that language for the analytical minds of your implementers.
You then need a vehicle to communicate this translation: So, naturally, you go hunting for that mythical template, and set out to write a document.
Let's then consider what has to be translated. Requirements really come in many different shapes, including:
- flow charts, for describing a series of events, or flow of information;
- lists and tables, for detailing data, and rules;
- images/mockups, for showing what the thing that we're describing is supposed to look like; and
- paragraphs, for describing what's left.
One quickly realizes that a single document can't adequately communicate all of these things. So, what do you do? You go beyond the document, and use a mishmash of the tools you have available: Perhaps you use Microsoft Visio for drawing out diagrams, Excel for lists and tables, PowerPoint for user interface mockups, and Word for everything else. And then you have to try and glue it all together (more on that, later).
At some point you send out the document you're working on, because communication is a two-way street (a point that a lot of people seem to forget). Unfortunately, documents are designed for one-way streets. So, instead of your reviewers being kind enough to comment directly in the document, we schedule meetings because they don't know how to make Word work, or they need you there to interpret what you wrote.... perhaps because they didn't read it! The cycle continues: You change the document; you send it out again, and then you cross your fingers and hope it will be reviewed in some intelligent fashion.
Who's reviewing these things? The challenge is that there are many people to please, and thus not one, but multiple audiences. Parts of your document are only relevant to certain people: High-level overview stuff is great for managers, but developers could care less about the "Project Vision"; and testers only require certain parts themselves. (Though one might argue that they should read this stuff, in order to provide context for the job at hand).
As a result, there may come a point where you break the document into two documents (at least): One document for business audiences, and another, with a lower level of detail, for a more technical audience.
To Validate that Needs are Met
Validation is where I say that what you think I said and what you say I said are the same thing, basically. (Got that?)
To do this, we need to connect the dots, or trace between what was originally said, and what it was translated to. This is also the part where it becomes necessary to add identifiers to everything, so we can reference them and find them, no matter where they are. Basically, all this means is that we end up putting unique numbers next to our requirements.
Ideally, we want to see how all these pieces fit together, so we aim to put everything in one document. In particular, what we're looking for is how the high-level needs will get addressed at a lower-level, by the implementers. However, if these two things are in two different documents, this makes things a little more interesting; not to mention we already have other objects spread across flow charts, spreadsheets, and slideshows.
This is where the idea of a "Traceability Matrix" comes in, which is not as cool as it sounds. The matrix is a table, created by hand, that shows how the stuff on the left is connected to the stuff across the top. In practice, however, because our documents become difficult to manage as they grow, these linkages begin to fall apart and we forget to update the table.
To Ensure Everything's within Scope
As our project evolves, we also discover that it would be nice to have this thing, and that we might need that thing.
By consequence, it quickly becomes apparent that if we don't control the size of the big thing that we're talking about, it will continue to grow, get out of hand, and then dinosaurs will rule the planet again.
Hence, a parking lot is born: This is a table of items that are "Out of Scope" that gets added to the document. This particular table shows us that yes, VP of Something, we listened to you ("Look, it's in the document!"), but no, we don't have the resources at the moment.
Of course, when the next project comes along, all of these items are buried in that document we worked on last year, and now everybody's forgotten about them, like fossils.
To Manage Changes to Requirements
Change happens. It's inevitable. And as you know, keeping track of changes in documents isn't easy: We have to record these changes, why they occurred, and who made them.
From the reviewer's perspective, they would like to see a big-picture view of what changed between the last time they saw the document, and what they're looking at now. Fine! This is where the "Revision History" table enters the picture.
But from your perspective (as the one wrote the document), it might be helpful to see what you had done before you went out to Starbucks after lunch, and promptly forgot everything. In an effort to try to keep a better record of things, we turn "Track Changes" on, and make sure our beloved document in a so-called "content management system", such as SharePoint.
Great! But what if lots of people are working on this thing? And what if your changes are spread across multiple documents?
To Meet Regulatory and Corporate Obligations
Documents are called into existence for regulatory, and other process-related reasons. In some industries, a process has to be in place, and a document marks a tangible point in this process.
Managers still want to put their monogrammed gold pen's ink on something tangible, sign on the dotted line, and have everything recorded so that somebody (namely the BAs that report to them) can be held accountable in case something goes wrong... which will happen, because nobody understood, or questioned the contents of the document in the first place.
Hence the list of "Approvers", with room for each stakeholder to sign and date the document, appears. The signatures on the printed document don't really mean anything, of course. Instead, this is something we like to call "the illusion of acceptance".
To Define Requirements Collaboratively
Whether you like your co-workers or not, you have to work with them to gather, document, and translate stuff. (There go all hopes you had of keeping things under control.)
As you know, building a document with other people is currently not a fun process: Documents are emailed back and forth, opened in Word, edited, comments are added, changes are tracked, you save the document, and then upload it to SharePoint, or email it back.
Recently, newer versions of Word are starting to make it easier to collaborate on documents with other people. Of course, reality tells us that even though these features are becoming available, your company's culture, and IT department, isn't moving as fast. (If you're like most large companies, you're probably stuck on Office 2003. If you're not, consider yourself lucky!)
The Death of the Requirements Document
So, what can we do to get rid of the big freaking requirements document? What's needed is a solution that addresses the reasons as to why they exist, namely:
To Communicate. We need to be able to express requirements in various forms, in one place, not across several tools. We should also be able to present/split/deliver what we have based on the audience we're talking to.
To Validate that Needs are Met. We must be able to tie needs and their detailed requirements together, through traceability. However, this should be a by-product of our work, not something we have to manually create and maintain. We should also be able to illustrate and animate to help communicate, and not just depend on legal-style paragraphs of text.
To Ensure Everything's within Scope. We should capture various levels of scope in one place, and only show what is needed. (Don't keep them separate.) Being able to easily see the relationships between all the detailed stuff, and what higher-level stuff it came from helps us to ensure that everything is within the agreed upon scope, as well.
To Manage Changes to Requirements. We should be able to manage change, see those changes over time, at checkpoints, and drill down to specific changes, as necessary.
To Meet Regulatory and Corporate Obligations. If possible, we should be able to move through an approvals process, without the need for a document. However, we should be able to generate a document if, and when it's needed.
To Define Requirements Collaboratively. We must be able to allow multiple people to work together, without tripping over each other.
In the end it's become clear that writing down and drawing out requirements in documents just isn't working.
The funeral for the big freaking requirements document must happen, if we are to move forward.
In Conclusion
Documents have been the de-facto standard way for working with requirements for years.
And given our discussion above, is it any wonder that software project success statistics are so dismal? (Some statistics suggest a 33% project success rate!)
Technology now exists that allows us to meet, and exceed all of the things that we had hoped documents would do for us, namely help to communicate, validate, manage scope, record changes, keep us compliant to regulations, and provide a collaborative medium for defining requirements.
It's time to let go of the security blanket. Big freaking requirements documents must die!
Don't forget to leave your comments below
Chris Gurney is a Training and Mentoring Specialist at Blueprint Systems, a provider of requirements management lifecycle solutions. For more information about Blueprint go to www.blueprintsys.com. Chris can be reached at chris.gurney@blueprintsys.com
Subscribe to this comment's feed
written by JoAnne Covington, March 16, 2010
-
- +7
-
-
written by Jeff Geurts, March 16, 2010
Specifically, Chris is introduced as a "Training and Mentoring Specialist" at Blueprint systems (www.blueprintsys.com) who provides that very thing :)
There are many other existing or emerging products targeted at requirements management (or at the whole development lifecycle), but it can be a long, painful process to adopt them so many companies are still getting around to it ;)
-
- +14
-
-
written by Erick Ulloa, March 16, 2010
-
- +2
-
-
written by Jon Borden, March 16, 2010
Requirements Management is a conundrum. Few would argue that complete, accurate, and unambiguous system requirements are not critical for a project success. The statistic you quoted above (the dismal 33% success rate for IT projects) is most often attributed to poor requirements.
The difficulty is, as you stated in your article, is HOW does one elicit, analyze, represent, validate and manage change for requirements. There are inherent flaws in the bloated Word documents, or collections of separate traceable artifacts. The maintenance of these, and the portability and flexibility are poor.
It seems that there should be a good technological tool that could help overcome these issues. Unfortunately you do not suggest any actual tool that can be used. Regardless, I am afraid that if one begins to look at the tools available, many of these become cumbersome to use and maintain as well (remember Case Tools).
The just in time requirements approach of Agile development may be one of the best solutions to managing this intricate issue. Unfortunately managing IT projects through the Agile methods requires large scale changes for organizations used to a more waterfall approach. In the meantime the BAs are in a conundrum.
Requirements you can’t live with them, you can’t live without them.
-
- +5
-
-
written by Chris Gurney, March 16, 2010
Thanks for the comments! I'm glad we're really all in agreement here.
My main point is that documents just aren't a great vehicle for communicating the rich variety of "stuff" that makes up a set of requirements for some system.
And yes, I do work for a vendor who provides such a solution, so of course I'm a bit biased. That said, I'd love to see more innovation in this category, as we all see it as a common problem that needs to be addressed. I'd love to hear your ideas for alternatives.
Keep the comments coming!
Chris.
-
- +0
-
-
written by David Hodgman, March 16, 2010
Dave H.
-
- +0
-
-
written by Robyn Harris, March 16, 2010
What hasn't been addressed so far is corporate governance. Management are always going to want to, in fact need to, be able to sign off on something that clearly defines what the funds are being committed to: i.e. what are they paying for – a 4 cylinder Toyota or an 8 cylinder Ford.
Additionally, there needs to be evidence in the case of litigation for non-performance/non-delivery: think IBM v New Zealand Police – each sued the other! Interesting case if anyone wants to Google it!
We also need to frame requirements documents for the audience. What I am reading here involves some tools that I would never use for documenting User Requirements - way too complicated for users to understand. Realistically, most users do not understand flow charts, in fact many may never have seen one - these belong in an entirely different project document. Years ago, we wrote User Requirements for users, then Functional Specifications and so on.
User Requirements were relatively simple documents as far as language was concerned, because they documented only the interpretation of what the user wanted, not how the solution was to be designed/developed/delivered.
Is part of the problem that we now want to have one document that is trying to be all things to all people? Not possible. Sticking to the KISS principle may well solve many of our problems. New tools like fancier Word, Visio, Sharepoint have perhaps let us all down the path, unintnetionally, of encouraging us to think we are "saving time" by consolidation, when in fact we have done nothing more than complicate the whole thing by trying to address too wide an audience.
-
- +2
-
-
written by Colin MEGSON, March 16, 2010
If business representatives have identified 100 functions that a new or replacement application must perform then these must be elicited, documented in a clear, concise and unambiguous way then managed.
•The business owner (or the person paying for the new application) needs to understand exactly what they are getting for their money,
•If developing in house, the developer needs to know what to develop,
•If out- sourcing, the software house needs a basis to make a quote,
•If purchasing a package, the purchaser needs selection criteria.
•The tester needs to know what to test.
Using a wiki or a requirements tool is not going to make the issue go away it is just replacing one technology with another.
As JBorden says: ”Requirements you can’t live with them, you can’t live without them.”
-
- +3
-
-
written by leslie munday, March 16, 2010
Although I have managed to seriously maim BFDs, I agree that it is very difficult to kill them outright, but here's some pointers I use when considering 'what to do instead'.
Where the BFD attempts to be a single solution to all development environments (and fails for the most part), there is no 1 single magic bullet - each project needs to address the following issues and work out their own answers for their own unique environment.
- Use the right tools for the job
Firstly, get it out of the developers heads that MS Office (or whatever document processing tools that you are using), is a development tool. My take on this issue to advertise MS Office as a 'reporting' tool. Just like SQL is a tool for generating database reports, (I'm not a SQL expert so I may not know what I am talking about, but would you really use SQL queries to populate your Megaton database?), MS Word is a great tool for generating reports on the state of your requirements, but not for maintaining them.
- Identify the requirements for developing the requirements
Continuing on the 'right tools' line; prior to creating any requirements, how about putting some effort into deciding what it is that you need to create and documenting the requirements for a toolset that is going to help manage those requirements. Anyone familiar with the Requirements Management Plan? The RMP can be used not just to identify what requirements, their purpose and their structure, but also to sketch an environment for managing those requirements. Write the RMP before you start capturing stakeholder needs with MS Word.
continued..
-
- +3
-
-
written by leslie munday, March 16, 2010
- Who is your audience?
Go find out what the roles are that are consumers for the requirements. For each role, write down what it is that they want to see in terms of requirements. Do they want use case text? Do they want activity diagrams, class diagrams, sequence diagrams? (The RMP is a great place to capture this information.) Once you have identified the roles and their needs you can develop reporting templates that are appropriate for each role.
- KISS
Keep it simple? How many times have you heard this phrase? How many times have you seen it ignored? A 'best practice' that I use in teaching .. 'If there are 2 ways of doing something, pick one that works and stick with it'. A good example is with UML diagrams. UML tries to be all popular notations to all modelers. I find that it allows a modeler to represent the same notion in several different ways. If you come across 2 artifacts representing the same thing in different ways, come to a resolution over which is 'correct' and make sure that everyone understands .. 'this is how we are going to do it', from now on.
continued ..
-
- +3
-
-
written by Sameer Bendre, March 16, 2010
Has anyone worked in a agile environment - AND used requirements doc?
Would we need requirements mgmt tool in an agile environment?
@Colin101 - Using Scrum the "business owner" or more correctly the product owner would be involved in defining product backlog that would be used to create, test and deliver "verifiable result".
Everyone:
How do we as BA's bring value in helping create a value driven result instead of going back and forth with the customer of just our interpretation? Why not collaborate?
Do we REALLY need requirements repository? What do you store in it? Another bunch of documents?
-
- +2
-
-
written by leslie munday, March 16, 2010
- Organization
Ok, so now you have broken down your BFD into the smallest manageable chunks. You have created all the reports that your users have asked for and you have structured your requirements via a RMP. The biggest threat to the success of your new restructuring is 'organization'. With so many little pieces floating around (in place of that one Dinosaur document that captured everything in one place), it is going to be easy for users of your requirements environment to lose things, or to get lost. Organization is unique for each project; there is no single solution that is going to work for everyone, and that is why this may be the part of the effort that needs the most work. A good place to start may be a Wiki, or SharePoint, or some other such centralized requirements artifacts repository. In choosing this structure, perhaps you might want to consider the following:
. how do I connect related things together?
- how do i manage versioning?
. for each of our users, how do we make sure that they have easy access to stuff they need without having to navigate through stuff they are not interested in?
. what read/write access does each role require (security)?
. how do I connect all my tools together, without having to duplicate stuff all over the place (another of my 'best practices' - duplicating information, causes more than 2 times the work).
- Get everyone on the same boat
Make sure that everyone that is involved with the requirements repository has their say into what they would like to see from it. Just like when gathering requirements for a project; the requirements repository is a tool that has user/stakeholders and SMEs. If you haven't addressed their needs, then why should they use it?
(On the last point you could ask, how do we capture and organize the requirements for the requirements management environment? My first response would be 'Use a BFD'.)
All the best, I'm on your side,
Leslie.
-
- +2
-
-
written by Carol Anne Wall, March 17, 2010
Are you including the UI, data, or reporting design specifications? Those aren't REQUIREMENTS, they describe the input fields. They are design detail. If they're taking up too much of your document, put them in a separate document.
The problem that my work group has, and that I think this article describes **perfectly**, is that they describe everything as requirements. Requirements are "descriptions of the necessary and sufficinnt properties of a product that will satisfy the consumer's need." (Gottesdiener, "The Software Requirements Memory Jogger", pg. 1) The consumer's need isn't to describe in detail the length of an input field, the database calls, the detailed layout of the report. The consumer's requirements are simplier and at a higher level.
Requirements are high-level expressions of need.
Design is the detail needed to program and test the product to meet the need.
Requirements influence design.
Also, in my 15 years of experience, the people who complain about the requirements documents being too big are the same people who complain that they want everything all together in one place when someone splits out the design specs. You can't have it both ways, people.
I'll be very interested to read your ideas for reducing the size of the requirements document, especially if they include something other than removing the design from the big honking document.
Carol Anne
-
- +4
-
-
written by Doug Bonebrake, March 17, 2010
The real issue is that large projects employing standard waterfall approaches produce volumes of word processed or graphics documents that nobody wants to read and find it impossible to search, navigate and trace. The challenge is for each project team role to be able to find the information they need, when they need it, without ambiguity as to what must be done to provide a technical solution to the business need. The final documentation set is also required for purposes of maintaining the configuration definition of the as-is system for purposes of education, maintenance and potential re-use for future endeavors. Add to the equation distributed (virtual) project teams and the challenges mount.
The true problem Chris mentioned is not so much the information required, but the tools available to support the capability to visualize the problem domain, search and trace the relationships and manage the communication work flow between roles throughout the SDLC. I agree that we need to stop using MS Word as the tool to manage the information, but the problem domain must still be analyzed and documented, for even in agile teams, memories fade and perceptions change with time.
We have various tools that work portions of the SDLC, but the holy grail is the tool that will seamlessly help us manage the analysis and information flow for the entire SDLC from inception to implementation in a manner which enables each role to visualize and drill into the information critical to the performance of their tasks - oh, and don't forget SOX, PCI and HIPPA and other compliance standards. In the meantime, we will need to cobble together the tools available - but there is hope as I am sure great minds are working the issue.
Doug
-
- +0
-
-
written by Martha McCullough, March 17, 2010
-
- +1
-
-
written by Dan, March 17, 2010
Every conceivable requirement type is in our DB (which is web accessible). That includes Use Cases, MisUse Cases, BRs, Design Solutions, Test Case references, etc. I can't image managing all the trace relationships without a requirements management tool.
It takes careful planning, the willingness to start over if the DB structure isn't working, and of course a content management process. I think the payoff is worth the ability to minimize the need for maintaining the "big freakin" MS Word and MS Excel work products.
-
- +1
-
-
written by steve, March 17, 2010
There have been times where I attempted to forced clarity with a simple, short document (using visual modeling etc), -and the business wasn't ready to digest that document. I think they're just used to long documents that they've forgotten the concepts of clarity with simplicity.
-
- +0
-
-
written by Keith Barrett, March 17, 2010
It sounds like most agree that the medium of the document (or spreadsheet, or Visio diagram) is often inadequate for the task but yet, even with most requirement management tools, that's still what we're stuck with when it comes time to share our requirements with our stakeholders or down stream counterparts.
The question then becomes...how else could I share my requirements for the purpose of validation and review?
(continued)
-
- +0
-
-
written by Keith Barrett, March 17, 2010
That said, when I saw the visual validation capabilities of Blueprint's Requirement Center I saw something for the first time that I believed could change the game substantially for the BA. I realized that it could enable the BA to share their requirements in a way that was easy to consume by stakeholders, thereby, improving the quality of feedback and, appropriately, the requirements as well. I was so impressed that I spent the next year working my way into the company so I could be a part of what I believe will change our industry.
You can crucify me if you want, for going to the "dark side," but you owe it to yourself to check it out and see if it just might be the "what else can we use" that we all know is needed.
Regardless of what you do with Blueprint's product, I think we all agree, the BFD or even lots of little documents, just aren't the best solution when it comes to asking the stakeholders...Can you review this and tell me if a got it right? As such, we should all be pitching in suggestions for what we think would truly satisfy this need.
Keith
-
- +0
-
-
written by David Wright, March 17, 2010
Speak for yourself.
The thing is, a document is just a container, it is what you put in it that counts. And what you put in it had better be something that somebody needs to do their part in the project.
Users have to verify the requirements in the container are what they said they were when they were being discovered. Requirements are distinct statements of functionality and information needs.
Designers and Developers have to know what the requirements, so they will deliver a solution that meets them.
Testers have to know what the requirements are, so they can determine if the delivered solution did actually meet them, or not..
So, Requirement Statements have to be traceable through design, code and test cases. Start with a list, a spreadsheet matrix, or a requirements tool of some kind, as long as the links from start to finish (and back) are clear.
So, in the end, it is the content that matters, not the container.
-
- +1
-
-
written by Keith Barrett, March 17, 2010
That said, I personally also believe that the container equally matters. I've said for years, the problem isn't so much that BAs don't know how to write good content. More often than not, the problem isn't the content, it's the container being used to share the content.
The container impacts the consumer's ability to digest the content...like trying to drink from a welded shut container. Sure, the content is good but the effort to consume it, dictated by its container, often causes the consumer to say "thanks, but no thanks."
-
- +3
-
-
written by David Wright, March 17, 2010
Hmmm... the way I work, the business people have seen the content being created, so its not new to them when the doc is finished. I suppose I have found that once the business people have agreed with the content, it is more readily accpted by the other audiences who receive it.
Given that, your comment has reminded me that I do work with a very good standard container, a document format developed by some smart people over time with experience. And, you can download it for free over at iag.biz. Have a look at it, I would be curious to hear yours and others' opinions.
-
- +0
-
-
written by Nan, March 18, 2010
-
- +1
-
-
written by Keith Barrett, March 19, 2010
What would interest me would be to see how much of an improvement in the quality of the requirements you would accomplish by using a more visual validation approach, i.e. simulation of the requirements - not prototyping of screens. It is still my thinking that even with the best of document templates and process that the human brain digests and comprehends input better from a visual centric approach verses a written or documented approach. I think people struggle in their mind's eye when they attempt to "see" the application via the pieces and pages in the document. Whereas a simulation brings all the pieces together in a rich visual context so it's easy for the consumer to understand how everything fits together.
-
- +0
-
-
written by Phillip Avelar, March 19, 2010
I think we need to remember that the requirements document is not the purpose of all the work that goes into developing it, Chris has a little bias as he works for a tools vendor but the idea result maybe his tool or any other that allows you to generate the details of the requriements document but have it a living breathing online document that maybe you never print.
We see these days many company looking at new approaches that skip the requirements phase because the impression is that the end result, the requirements document is not useful but the reality is that these same companies are suffering throughout their development phases because the analysis work that goes into developing a requirements document forces the interviews, questions, and overall thought process that develops better software. Not to mention that those same companies suffer in future development projects because the details of how the current software was developed is missing or poorly documented.
Let me sum it up this way without writing a whole blog posting. The benefit is the journey not the destination.
Phil
-
- +1
-
-
written by Ariel Anderson, March 19, 2010
Ariel (I don't have any affiliation with this software company, I just crave a tool like this)
-
- +1
-
-
written by meb006, July 01, 2010
Business analysts should be demanding visualization tools to get their job done better and faster. There are a number of vendors that offer a wide range of visualization, prototyping and modeling tools that empower BAs to quickly assemble working previews of proposed software (full disclosure - I work for iRise, one of these vendors). The magic happens when your stakeholders see the following:
1. they get to see, interact with and fully experience software without coding
2. visualizations are easy to understand - a picture is worth a thousand words, right?
3. the visualizations are super fast to produce
4. the group gets to rapidly iterate right in the stakeholder review session, dramatically cutting requirements cycle times
5. visualizations can be easily shared with global teams
6. text requirements can be documented in the visualization and associated with elements on the screen
7. reusable visualization content enforces best practices and speeds up the next project.
Adopting visualization is a people, process and technology transformation. But the time has come. The future is here and BAs need to be leading this transformation.
-
- +0
-
-
Click Here to login or create a free account.
my big concern is how could we do all the followoing if the requirements document died:
1- communicate.
2- Validate the Needs are Met
3- Ensure Everything's within Scope.
4- Manage Changes to Requirements
5- etc.....
as you mentioned above there is no specific solution to handle all the related activities to the requirements documentation, so what are we going to do if we kill the requirements document ????