| date: | 2007-08-05 23:09:37 |
|---|---|
| category: | War Stories and Advice |
See So What Are Requirements? in Dr. Dobb’s.
I’ve seen requirements done badly. I’ve seen some notable failures of the use case technique: almost entirely because people refuse to actually apply the technique; they refuse to write use cases from the actor’s point of view. I’ve whined about this before in Notable Failures of Use Cases, part 1 , part 2 , part 3 , and part 4 .
The interesting point that Wiegers makes is that there are different species of requirements. Failing to recognize this is what can lead to diluting the use cases with junk.
The summary definition (from Coyote Valley Software principal Brian Lawrence) appears to be that the line between requirements and design is that requirements lead to design choices. While I like this, it has to be refined a bit.
Pressman calls this the “What vs. How” distinction. Requirements specify what must happen. Design chooses how this will happen. Again, this needs some refinement. In a way, Pressman throws up his hands in despair, noting only that there is a hierarchy of what’s and how’s. For example, interface requirements are “how” we’ll implement some business requirement. On the other hand, the interface requirements are a “what” to a lower-level piece of software that opens and closes sockets.
Exacerbating this hierarchy problem is more fundamental confusion on techniques to capture requirements in the first place.
Point of View
Recently we were working through some use cases where the author had identified a document as the actor. The body of the use case was a bunch of technical processing details for the document. It’s painful to claim that all 20 use cases weren’t use cases because the actual actor (the user who needed to see the document’s processing) was never mentioned even once.
At some point, the customer trotted out a use case with no actor. The use case summary had a passive-voice construction (“will be notified”) At that point I could drop the bomb that use case actors are usually people (sometimes they are interfaces) by asking “for whom?”
The customer’s project manager made the claim that he thought that use cases were written from the system’s point of view.
“Technical” Requirements
I told the customer’s team that it was a common misconception. It arises because of the vast wealth of technical details with no obvious home when writing use cases. They wanted to call the details “technical requirements”. I balked.
Wiegers suggests that we have business requirements, user requirements (the proper use cases) and functional requirements. This certainly peels the outermost layers of the onion, and is a potential tool for guiding people into writing usable requirements. But it has a small problem.
The name “functional” requirements is a fairly serious problem with Wieger’s breakdown. Most people don’t know what constitutes non-functional requirements. Consequently, they just throw the phrase around more-or-less at random. I have to object strongly when I’m shown a document with dozens of pages related to performance, maintainability, and ownership issues – all non-functional requirements.
The core issue is that everyone wants to design the solution. The more people you interview, the more you discover that everyone is an architect, and everyone has very strong opinions on precisely how to build the software solution.
At every level of the organization, you’ll hear the following: “I’m not technical, but wouldn’t it be simpler if...” followed by some kind of design. If I remark on how their solution might have issues, they’ll explain to me that one of their non-technical staff built something like their preferred solution in MS-Access during lunch-hours over the previous week.
The Why Cases.
Rather than ask “If your staff member is such a hot-shot programmer, why am I here?” it becomes important to dig into the real requirements.
I find that we have the following kinds of requirements. These aren’t presented in a top-down order, but in an inside-out order.
Passive Voice Reporting.
One of the best indicators of confusion seems to be the passive voice constructs like “the exception report will be generated daily.” This invites us to ask two questions:
For whom? This question will let us locate the proper use case. Generating an exception report doesn’t involve any interaction. Someone looks at the exceptions, makes a decision, and takes action. Who does this? What are they supposed to do?
Why? This question will let us locate the driving business requirement. For example, we may have a contractual obligation for a particular service level. Someone must investigate each exception, determine a root cause, and take action to correct problems that are internal and finish processing the exceptional transaction.
Customer Guidance.
What do we do when we’re confronted with stuff that isn’t really a requirement? Generally, we’re given design documents with titles like “Software Requirement Specification” or “Use Case”. Since the documents don’t allow us any design choices, they aren’t really requirements; they’re specifications.
All too often, folks have downloaded an SRS template (like Wieger’s ) and then abused the template. I’ve seen SRS documents with the titles and template instructions still in place, essentially ignored by the author. Large sections of the SRS template are left empty, because the author wasn’t writing requirements.
I think that we need to look at the design documents we’re given ask the two fundamental questions: why? and for whom? From these two questions we can back up to the business requirements and the use case.
Hopefully, we can achieve a fundamental rethinking of the specifications to improve their value in a number of ways.
The Architect Gets a Bentley.
Defining who does the job gets us away from writing software that seems necessary to the author (“of course we need notification of exceptions”.) It can help us locate software that really is essential (“typically, Frank checks the exceptions each once or twice a week by looking at the logs, not a report”). If it isn’t going to be done daily, why over-engineer the system? If the logs satisfy the need, why design a report? Why not target the implementation for what people will actually do?
Including the business requirements can simplify or focus the use cases. If we can’t articulate the business need, then we have the I Get A Bentley™ requirements.
I had a customer claim that they required 24x7 availability. But they would not consider any hardware changes, and the hardware they had purchased couldn’t provide the level of availability they were asking for. When I brought this up, they claimed that 24x7 wasn’t really a “requirement” it was more of a “goal.” My follow-up question was “Where’s the line? What’s the least availability that you’ll tolerate before you sue me.” They chuckled nervously, and said that any talk of lawsuits was irrelevant.
It isn’t irrelevant. “Required” means required, as in “if the system doesn’t do this, you don’t get paid.”
If 24x7 availability is a requirement, then “Architect gets a Bentley” is also a requirement. There’s no business justification for either position. They were clearly a 12x5 operation, and could justify requiring 18x6 to cover weekends and west-coast timezones. They could not show a business reason for 24x7 any more than I could show a business reason for a Bentley. It may have been my goal, but I couldn’t justify it as a contractual requirement.
The Bentley Test.
If the answer to “why?” is isomorphic to “because I’m the customer,” then you’ve located a place to apply The Bentley Test™. If you get feature [X ] because you’re the customer, then I get a Bentley because I’m the architect. It sounds fair to me. Prove that it isn’t.
Phrases like “you must have known we wanted this when you wrote the proposal” or “if we didn’t want that feature, why would we be building software?” are isomorphic to “because I’m the customer.” Other examples include
Sure, and I get a Bentley.