Write your stuff with users in mind

If an IT project team doesn’t understand the requirements for a system, it doesn’t matter if it’s using the latest object-oriented methodology or development tools. Ideally, the team could create a requirements document entirely on its own, but since systems are built at the request of business-unit end users, the document can’t be created without their input.

So, why not have the business users document the requirements, with the IT project team reviewing them for completeness and consistency?

How can we help users accomplish this?

The most important thing is to persuade them that it’s worth the effort. Techniques and procedures are useless if the users complain that they’re too busy to waste their time on “that technical stuff.” Anyone who has interacted with a contractor to remodel a kitchen knows that it’s crucial to describe requirements as specifically as possible. Unfortunately, many end users haven’t had that bitter experience in IT; after the second or third disaster, they’re usually more amenable to the suggestion that they get deeply involved. But that’s hard to do the first time around.

Even if users do agree to invest time and energy in writing system requirements, their time is limited. No matter how enthusiastic they may be, they won’t have time to attend a five-day requirements-writing class and then churn out 900 pages of documentation. Thus, one question the IT project team must ask about each requirement is: “What happens if we don’t get this right? If you document the requirement incorrectly, or if we don’t understand it properly, how bad will it be? Will lives be lost? Or will it be a minor nuisance that can be corrected later?” This allows the users and the project team to prioritize their efforts and write a “light” document for systems requirements that don’t matter much, and a “heavy” (or formal, rigorous and detailed) document for requirements that will have a life-or-death impact on the business.

The next question to ask business users is, “How well do you understand your requirements?” Software-engineering literature often assumes that users understand their requirements perfectly and that the problem is simply one of articulation and documentation. But if the users say, “No matter how much thinking I do about the situation, I really won’t know my requirements until I see how the system works in the real world,” then we’re kidding ourselves if we try to force them to document their requirements in mathematical equations. That’s why the idea of building several interim prototypes – in order to get feedback and confirmation of the “real” requirements – is so popular, but the trick is to reserve prototyping for situations in which it’s needed, rather than using it as an excuse to avoid documenting what we do understand.

Finally, while reviewing the requirements document that the users have drafted, we need to ask, “How would you test the system in order to ensure that we’ve successfully implemented this requirement?” This is one of the basic tenets of the XP (extreme programming) movement, but it’s often interpreted as a discipline for programmers to use among themselves – that is, no code shall be written before the test case is created. But if we broaden this concept, we can get users and business analysts involved in the same process: Write the “acceptance test” before writing the specification. This helps expose ambiguous and unacceptable requirements such as, “The system shall be user-friendly,” because the people who write such statements have rarely thought about how a system would be tested.

None of these ideas constitutes rocket science, but they’re not easy to implement. Unfortunately, some users will never learn that it’s worth the time and effort to create well-formulated requirements, and the unpleasant consequence is that nearly all projects that get carried out for them will be frustrating failures.

Yourdon is editor of Cutter IT Journal, published by the Cutter Consortium in Arlington, Mass. Contact him at www.yourdon.com.