Wednesday, December 23, 2009

If You Only Ask One Thing...

When you have a specification to review, it's your chance to find major holes early on. The problem is that specifications are often (although not always) feature-oriented. They'll include screenshots of individual screens, or they'll have a set of API calls and a brief summary of the purpose of those calls. This is all great information. But in the end, no one uses an API call or a screen. They use a system. They use a system to accomplish tasks.

So whenever you look at a specification, take the tasks the customer will do and ask yourself one thing:

The user sits down in front of the system. Walk through what they do to accomplish task X.

This will expose a lot of holes. For example:
  • An upload API with no way in the GUI to actually review what is uploaded
  • A cleanup process that leave the system unusable for hours on end
  • A background process with no ability to start or stop it
  • And a lot of other things...
What a system does is important, and a specification can describe it. But in order to know if the system hangs together as a whole, it's important to consider the tasks and the workflows of the system consumer.


  1. This is also, IMHO, a strong plus to user stories, compared to a list of specs.

    The "As a logged-in user, I want to do upload a photo so that people can view it on my profile page" format encourages developers to think in terms of users' full-stack, end-to-end behavior.

    Furthermore, you have to act out that user story to confirm that it is sufficiently complete.

  2. "Acting out" is a great way to put it. After all, sometimes stories can skim over details and have the same problems that a functional spec does. But when you "do" it (even if only in your mind), you're likely to see holes.