What Is the Right Level of Detail?

A couple of weeks ago I presented an overview of More About Software Requirements – Thorny Issues and Practical Advice by Karl Wiegers. Today, I am going to drill down a little bit further into one of the sections that I thought was particularly well done.

Part V of the book is titled On Writing Requirements and it presents a detailed tutorial on some of the tips and techniques that Karl has seen work successfully during his years of requirements work. The section includes 5 chapters:

• 12 - Bridging Documents
• 13 - How Much Detail Do You Need
• 14 - To Duplicate or Not To
• Duplicate
• 15 - Elements of Requirements Style
• 16 - The Fuzzy Line Between Requirements and Design

Karl starts Chapter 13 with a key question that I believe does a fantastic job of capturing the crux of the “how much detail” discussion:

Who do you want to have making requirements decisions and when?

In my opinion, too few organizations follow the advice that Karl presents for answering this question. His suggestion is that companies need to balance cost and risk as they seek to determine how much information needs to be included in the final requirements. Simply put, the amount of detail included in the requirements should be determined by calculating the risk that would be involved in allowing developers to fill in whatever gaps remain. Unfortunately, my experience has been that many organizations are not able to evaluate this equation quite so dispassionately. In many groups, there are long wars waged over the amount of detail that is “sufficient” with large amounts of energy expended on what essentially boils down to a turf war.

A great example of this that I have witnessed is from a company where the founder was still CTO. He wanted nothing to do with formal requirements for the entire organization since the people on his team didn’t need them - they were the domain experts who best understood the users’ needs and how to solve them. Unfortunately, what he didn’t acknowledge was that the ability of the development staff to live up to this expectation decreased drastically once you moved beyond the CTO’s immediate orbit. What may have been true for the core team that had been around for years was anything but for some of the people that had subsequently joined during the growth phase.

As expected, Karl does not come out with an answer as to what level of detail is “just right.” Rather, he presents a spectrum of situations where the level of detail required will shift from “less” to “more.”

More Detail Needed

• Development will be outsourced
• Project team members are geographically dispersed
• Testing will be based on requirements
• Accurate estimates are needed
• Requirements traceability is needed

Less Detail Needed

• Customers are extensively involved
• Developers have considerable domain expertise
• Precedents are available
• A package solution will be used

Whether it was intentional or not, Karl seems to subtly point the reader towards the “more detail” end of the scale. For each of the bullet points above, he provides a few paragraphs of explanation. When describing the “more detail” situations, Karl is uniformly positive in what he has to say. The “less detail” descriptions, on the other hand, include many negatives. For example, the phrase “watch out” appears repeatedly when discussing the scenarios that call for less detail. I can understand Karl wanting to explicitly warn readers who might jump too quickly into the “less detail” end of the pool, but I think the section could have been made stronger if he had included similar “gotchas” when discussing the “more detail” situations.

All in all, I believe that Karl effectively used this section of the book to tackle a tricky question. Trying to find the right level of detail for a requirements document will almost always be a challenging judgment call for an organization. The odds of successfully navigating this decision in your company can be increased however if you make a conscious, rational examination of your unique situation and carefully evaluate the tradeoffs involved.