Requirements Details – How Much is Enough?

What is the right level of detail for writing requirements? What about for writing specifications (functional, non-functional requirements, etc)? The answer is that there is no one answer. But there are guidelines, and reasons to write more detail, or less detail – for any given product or project, and any given team. The reason we write requirements is so that they can be read. Understanding the readers is the key to determining which details to include in the requirements.

Requirements for Agile Teams

Steve Johnson and I had a great discussion this morning about his webinar from last week, Extreme Product Management. Steve’s presentation is really good, and worth a listen to answer questions about how to combine product management and agile development teams to achieve market-driven product successes.

As part of a follow-up, Steve and I got to talking about how much to document for agile teams. A few hours later, he shared a slide with me that he had put together, that provides a great visual of the concept. In short, the more your team knows about your domain, the less documentation details they require to be effective.

[click for larger version]

Generalizing The Relationship

Steve’s slide is well designed for the “who do we need to be effective with an agile process?” question. And it can also lead us down paths that consider outsourcing, in-sourcing, off-shoring and co-location of development teams. That isn’t necessarily where we want to take the discussion for this article.

What Steve’s slide (not from the webinar, by the way) illustrates is that different audiences respond differently to different processes. From an understanding of how agile processes work, we can extend this idea – we need to write differently for different audiences.

Generally speaking, the more you know about a domain, the fewer the words needed to convey a concept (or requirement) with precision. Without using jargon, you can still communicate more concisely. Remember, though – the goal is clarity, not brevity. For example, it is much easier to describe the concept of drafting when speaking to a racing fan. [Note: drafting is riding or driving close behind another competitor, in order to benefit from the reduced aerodynamic drag.] When someone already knows what drafting is, providing instructions on how to do it is easier than if they do not.

Use Case Details

At this point, you may be thinking but there is a right level of detail for use cases. Alistair Cockburn talks about the level of detail for describing use cases in Writing Effective Use Cases. Jeff Patton has a good article explaining Cockburn’s levels. Cockburn uses a metaphor of elevation:

• Cloud Level – very high level summary
• Kite level – summary
• Sea level – “single sitting” task descriptions
• Fish level – small tasks that add up to valuable tasks
• Clam level – very small details that make up small tasks

Cockburn suggests writing at three levels – summary, user goal (sea level), and sub-function (fish) levels.

The authors of Patterns for Effective Use Cases present an interesting pattern – EverUnfoldingStory (pattern 4.5, p102). They point out that different readers of use cases need different levels of detail.

An architectural analysis may only need very high level details of the use cases. Other readers of the use cases may need to understand the interplay of use cases at a more detailed level. And individuals may need to understand a particular use case in even more detail, while only needing a higher level understanding of other use cases.

The suggested pattern is to use multiple layers of use cases that can be “drilled down” into to get more detail, and can be rolled up (and hidden) to obscure detail when it isn’t needed. The clearest way to achieve this is with subordinate use cases.

This seems like conflicting advice – write for your audience, and write for all audiences.

Supporting Details

The language you use should be adequate for anyone who has a reasonable level of understanding of the domain. For example, in a business application, it would be appropriate to use language like “The system will report the net profit of the sale.” It would also be appropriate to specify a business rule that “All companies with EBITDA below 5% be treated as high-risk investments.”

When your team needs it, you should provide explanations and definitions in a glossary of terms. The level of domain expertise determines how much explanation you need to include. As a product manager or business analyst, you ideally should not have to document the definition of “net profit” and EBITDA. You aren’t teaching a course on financial accounting, you’re specifying a product. You should be able to reasonably expect that team members understand, or can easily find definitions for these industry terms.

You might need to define (or link to a definition of) HHI, or other more esoteric terms. You can’t expect your developers to have MBAs. You absolutely need to define any terms that are specific to a single customer (product managers cover your ears). For example, the method of allocating overhead. As a rule of thumb, management accounting terms would need definitions, as they are often interpreted differently by different companies. You have to find a balance, by understanding who is reading the documents, as to where you draw the line.

In practice, make sure that you have budget and time allocated to deal with this. When your company leans more towards the “development factory” model – treating people who sling code as a commodity, you will need to allocate more time and effort towards education. Recognize that you will be articulating business requirements, in a language that requires some understanding of business terms. If you can use that knowledge to influence how you staff the project, great. If you don’t plan ahead, you might get lucky – but more likely, you’ll find yourself with scope creep, or missed estimates.

How Have You Dealt With This?

I’ve been on projects where the implementation team had deep domain expertise. The communication was very efficient. I’ve been on projects where the team was able to very quickly gain that expertise. Those teams needed some early education, but very quickly became efficient. And I’ve been on projects with teams that had no experience in the domain. It was like teaching them a new language – and unfortunately, we did not expect to have to spend time on that education. And it delayed the project. Eventually, they became conversant in the domain.
The best practice I walked away with was to not clutter the artifacts (directly) with these definitions, but to identify and link to reference materials, and an easily searchable glossary of terms. This allowed team members to drill down when they needed to, without being distracted by wading through unneeded information when they didn’t.

We would love to hear about situations like this that you have run into, how they caused problems, and how you solved them. Maybe there are better ways to address this stuff.