Have you ever written a requirement, or, more likely, business rule, that you know to be correct—but, you also know that many people will stumble over it? This usually happens when the language in the requirement/rule is not familiar to everyone or the concept is complex. In these situations, examples are usually more helpful than more words, such as:
- The number must be expressed using digits (example: “7” not “seven”).
- A = the ceiling of B/C (examples: ceiling of 10/3 is 4, 11/3 is 4, 12/3 is 4, and 13/3 is 5).
A colleague and I were discussing this the other day. He pointed out that sometimes examples are trite and provide more to read/review with no real value. I agree, don’t use them everywhere. As a guideline: provide examples if you believe at least some of the people reading the information will sketch out their own examples to understand the requirement or rule. Or, if you would provide an example if you were discussing the requirement/rule in person, provide it in the document.
There’s another place where examples can come in handy. Once, I was revising some requirements written by someone else. There was a log of detail, and I understood what was being requested. But, I didn’t understand the practical application of it. I like abstraction, which gives flexibility. Providing examples of how the abstract becomes concrete is useful. In these cases, be careful no one takes the example as a limit in scope. Perhaps you have a system that allows users to customize data entry prompts. One example would be that a person can change labels to another language. However, this doesn’t mean changing language is the only use. Some users may want to use different verbiage, while others may simply want to change the case of the prompt.
Need more help on clearly defining your requirements? Check out ArgonDigital’s comprehensive list of business analysis tools online.