Friday, May 23, 2008

An Example's Worth A Thousand Words

I read a fair amount of requirements. 

Some of them are incredibly sparse, like so:


Some of them are overly verbose without actually saying much, like so:

The system shall [EDIT: these seem to always start with "the system shall"] provide a login mechanism requiring two fields: username, and password. The username field shall be 56 px in width and 18 px in height. It shall require the use of characters as defined in RFC1920, part A. The password field shall be 62 px in width and 18 px in height. It shall require the use of the accepted subset of characters as defined in RFC1920, part B. ....

Some of them are a nice combination of defining without being useless, like so:

Login requires the user to enter two fields, username and password. For username definition, see registration requirements. For password security, see registration requirements. There are three allowed states:
- failure to login:  show error message
- successful login: show home page
- nonexistent user: redirect to registration page

But the best requirements include one important thing: examples. An example can clarify a requirement in far less verbosity than actually spelling everything out would. A screenshot is a classic case of an example; instead of describing layout and pixel dimensions (which would go on for pages and pages), it is a quick way to say, "here's an example. Make it look like this."

Examples are good for more than just visual things. Often they're good for allowable and not allowable inputs. To continue with our login example, we could easily describe the allowable characters (or character sets), but often people more readily understand when there is also a set of brief examples and why they're good or bad.

All this comes with one very large caveat: examples do not replace requirements. They supplement and clarify requirements. Unless the requirement can be entirely encompassed within the examples, you will also need to include the actual rules and restrictions of the feature.

Next time you're puzzling your way through some dense set of requirements, throw in an example or two; it's amazing how much more clear the entire thing will become.

No comments:

Post a Comment