It’s Demolition Time: Say Bye-Bye To Massive, Text-Heavy Requirements Documentation

A couple of days ago, Texas Stadium was reduced to a pile of rubble. Wow. The former home of my Dallas Cowboys, the site of victories and record-setting performances — gone in a matter of minutes. Was I sad? Yeah. But also a bit relieved. The Cowboys have moved to their new, super-duper (and quite ostentatious) stadium, Texas Stadium memorabilia has been auctioned off, and the poor, neglected building had become quite an eyesore.

Sometimes destroying something unusable is the best way to move forward.

Run that statement past your approach to documenting software requirements. When was the last time you took a step back to evaluate how your organization represents requirements? If it’s been awhile and your business analysts are still delivering massive, text-heavy, all-encompassing business requirements documents (BRDs), it’s time for some demolition of your own.

Why? Compelling forces have converged, drastically changing the way application development teams author software requirements. Organizations are recognizing the connection between software failure and poor requirements, and authoring better requirements has become a major initiative in many firms. At the same time, Lean and Agile are front and center, so right-sizing requirements documentation is on everyone’s radar. Bottom line, you need to do more with less: author stronger requirements while minimizing waste and being as lean as possible.

That begs a question: Assuming you accept the fact that the massive BRD needs to go bye-bye, what do you replace it with? Lean and Agile proponents will tell you to create “just enough” documentation to communicate requirements. But how much requirements documentation is “just enough”? I’ve been asked this more than once, so I’m doing research for an upcoming Forrester report. Here are a few of my initial thoughts:

  • Documentation doesn’t imply Microsoft Word. I’ve struggled with the word “documentation” for a while, because to me it implies text-centric artifacts. But the Merriam-Webster online dictionary defines a document as “something that serves as evidence or proof” and elaborates that the “something” could be writing, photographs, recordings, or objects. It’s not all about the words, and we need to get past associating “documentation” with “text” and begin to view it as an artifact or collection of artifacts — text, pictures, audio, and video — that helps convey information.
  • Business analysts (BAs) need to focus on the documentation’s intent. Requirements documentation helps teams collaborate, helps business analysts analyze, and communicates meaning to business stakeholders, developers, and quality assurance pros to help them understand what software the team is trying to build. It also documents a system for those who will interact with that software later. By understanding the purpose of the documentation, you can better hone its focus.
  • Requirements authors need to understand their audience . . . Many people — not just business stakeholders — consume software requirements, and all have different preferences. Developers may prefer use cases and wireframes. Quality assurance (QA) pros might benefit from receiving requirements in a data-oriented format. And, yes, your business stakeholders may be most comfortable with Word — but they need a pared-down version to digest requirements efficiently.
  • . . . And they need to consider the documentation’s life span. If you need to document requirements formally to prove compliance, do it. But don’t spend hours creating formal, perfectly formatted documentation for something that will never be referenced again. This is where the “just enough” test is most critical when you’re trying to become Lean.

 

A recent BA Times.com article clearly calls out: “The Big Freakin’ Requirements Document Must Die. Here’s Why.” I agree — and love the title! How have you moved from massive, text-heavy requirements documentation to something leaner and more efficient? I invite your comments on our blog site, or feel free to email me at mgerush@forrester.com. How do you know how much requirements documentation is “just enough”? I look forward to your feedback!

Comments

Sometimes

Sometimes all it takes to define the job is a hastily drawn scribble on a restaurant napkin. And sometimes it is a detailed description. Almost always pictures shorten the documentation.

Have you got any suggestions for tools to help produce / collect the necessary stuff without collecting a lot of "fluff?" As a free-lancer, the less expensive the better.

Desktop wireframing tools

Hi Nancy. Thanks for the comment. You would enjoy seeing my collection of napkins, sticky notes, and notepad pages with scribblings of all sorts. I even keep a sketch pad and fun markers handy to capture ideas. We have a market overview of requirements tools in editing right now - it should be published in the next week or so. During my research for that report, I came across a list of lightweight prototyping and wireframing tools. I'm not sure what types of projects you work on, but this may be helpful: http://www.uxbooth.com/blog/15-desktop-online-wireframing-tools/. If you're looking for other types of tools, let me know, and I can send additional information. Thanks!

I've seen it

I've seen that pile - right here on my desk! Thanks for that list, I will review it carefully.

Recently all my projects have been websites, from very simple to fairly complex. As a matter of fact, this blog site is one of them. (yes, I am the one to blame.)

One of the things that so often makes me stumble is not outlining data flow because I mostly work in MySql these days and I haven't seen any (affordable) tools that will model that data. Paper and pencil only works if you can remember where you put them and what has changed since the last time you saw them.

If not Word...

I really appreciate your take on Requirements Documents. In my world, we call them PRD (Product Requirements Documents). Over the years, I was proud to have the most meta-data to convey the context as much as possible without deviating from the JED doctrine (Just Enough Documentation). That being said, traditional text documents are indeed a pain to version effectively, to track, and to roll into the next iteration...

I was toying with the idea of leveraging wikis for requirements, allowing stakeholders to visualize the upcoming capabilities "in context". This needs instrumentation and/or methodology for tracking, etc. but it seems quite appealing for Agile development.

Have you seen any experimentation along those lines? Success? Failure?

Thanks!

Requirements Wiki's

Wow. That sounds fascinating.... Would love to see some follow up thinking on this....

Requirements Wikis

Thanks for the input. We have seen an increase in the use of Wikis for requirements definition with a fair amount of success, and some of the tool vendors are incorporating Wiki-like functionality into their products. We'll be running a survey of business analysts this summer with the IIBA, and I plan to explore this further. So stay tuned!

Texas Stadium style reworking of requirements process

Great observations, Mary. As a Packers fan, I can't say I was sorry to see Texas Stadium go (Was that eighth field goal oh so many years ago REALLY necessary?), but the idea of taking a hard look at how requirements get generated/documented etc. is one who's time has come. I'm hoping for marginally less smoke and noise than the stadium demolition, but not counting on it.

I'm finding that the term "requirements" through long usage and little maintenance has become something of a catch all phrase in our organization. Yeah we have BRD/PRD equivelants, but that's not the only context in which the word is used. Sometimes regulatory constraints get called requirements (well they are in the most abstract sense of the word). Technical spec's get called requirements (particularly mischevious because it invites folks in the business to be authorities on how stuff gets implemented whether they have any expertise in the area or not). So it not just the doc that needs revisiting, but the way our org talks and thinks about requirements.

Really looking forward to the early May workshop!

- Byron