Digestible Requirements

I commonly get "requirements" documents from clients that read like a college book report, just pages and paragraphs of disorganized stream-of-consciousness ramblings. When this happens, I use a little trick to restore some order to the chaos. I break it down into one long checklist of digestible tasks.

Why a big checklist? Several reasons:

• It's easier to digest smaller tasks in comparison to big paragraphs of verbiage.
  
• It's easier to organize and group those smaller tasks.
  
• It translates directly into a test plan; every checkbox is a test that has to be written.
  
• It gives me a pretty decent status report and evidence of progress and I work through the list checking things off.
  
• Once everything is checked off, I know I'm finished. I know that I've satisfied the client's request.

Here's how I typically go about it. Let's use this as an example "requirement" from a client:

"We're tired of users mistyping their passwords and not being able to access their new accounts. First of all, we want to add a password confirmation field to the sign-up form. Secondly, we want to force them to pick a password between eight and twelve characters. This should make their accounts a little more secure."

For the moment, set aside the issues of usability and obscurity over security; those topics are outside the scope of this discussion. The first thing I do is break the document into a checklist where every sentence is an item on the list. You can do this pretty quick and dirty with a simple regular expression find and replace of every period with a carriage return and a checkbox. This gives me something like:

[_] We're tired of users mistyping their passwords and not being able to access their new accounts.  
[_] First of all, we want to add a password confirmation field to the sign-up form.  
[_] Secondly, we want to force them to pick a password between eight and twelve characters.  
[_] This should make their accounts a little more secure.

Now you'll probably notice that the first and last items aren't really requirements, they're just an opinion and a speculation respectively. They can be removed, leaving us with:

[_] First of all, we want to add a password confirmation field to the sign-up form.  
[_] Secondly, we want to force them to pick a password between eight and twelve characters.  

Is the order important here? I don't think so. Let's get rid of that "first" and "second" nonsense:

[_] we want to add a password confirmation field to the sign-up form.  
[_] we want to force them to pick a password between eight and twelve characters.  

Then a little clean-up of the grammar to make it more declarative:

[_] add a password confirmation field to the sign-up form
[_] passwords must be between eight and twelve characters

Now comes a tricky issue. Whenever you see a conjunction like "and" or "or" or in this case the word "between" you're probably looking at multiple requirements in a single sentence, and you're better off breaking them up:

[_] add a password confirmation field to the sign-up form
[_] passwords must be more than eight characters
[_] passwords must be no more than twelve characters

By breaking it up into two separate items, we can writer better isolated tests.

As a side note here, try to keep in mind that most people don't think "logically" like programmers. When they say "between eight and twelve" they don't consider the literal interpretation of "greater than eight and less than twelve." In most cases they probably mean inclusive of eight and twelve. Make sure you clarify with them before taking their words for granted.

Now, depending on the situation and the particular client, I will probably pass this list back to them, asking for them to review it and confirm that I have accurately interpreted their prose. And in some extreme cases, I'll ask them to sign it.

Once I've got my checklist, I'm golden. I can write a test case for every item on the checklist. I can use the list to gauge my progress with the project. And when everything on the list has been checked off (i.e. all the tests pass), I know I'm done.