Thursday, February 14, 2008

Stories Should Say WHAT, Not HOW

We describe features as stories. This is incredibly standard in XP and other methodologies. A story usually goes something like this: "System allows user to log in with Active Directory credentials". Then it goes on to describe what that means, the tasks needed to implement it, and finally an estimate.

All good.

However, one thing that you have to be very very careful of is what you put in the story.

Stories should say WHAT the system does. Stories should not say HOW the system does it.

If a story says how, it forces the implementor into a design, and that design may or may not be the right way to do it. For example, here is a story two ways.

Story Describing What
----------------------------
Summary: Automated test logs bugs for failure
Motivation: Prevent QA engineers from having to manually parse error logs and log the bugs
Details: The automated tests currently spit out a results log with the test that failed. QA engineers go through, find the actual failure, and log (or update) a bug based on it. The automated tests should, for each failure, either log a bug or update an existing bug (if one exists already).

These bugs should be assigned to a QA engineer for review. QA engineers will manually review the bugs and send them to the correct developers. This step may be removed by a later story.
---------------------------------

Same Story Describing How
-----------------------------------
Summary: Automated test logs bugs for failure
Motivation: Prevent QA engineers from having to manually parse error logs and log the bugs
Details: The automated tests currently create a summary log with the test(s) that failed. QA engineers go through and find the actual failure, and log (or update) a bug based on it.

The automated tests should, for each failure, look up the test name in a database of prior test results, compare the failure with all related open tickets and determine if it's a new failure. If it's a new failure, the automated tests should log a new bug and create an entry in the database of prior test results. If it's a previous failure, the automated tests should update the existing bug and update the entry in the database of prior test results.
---------------------------------

In the second story, I'm describing not just what I want to have happen, but how it should be implemented. While the method described above is one way to handle automatically logging bugs, it may not be the best way. Nonetheless, my story is committing us to that particular way.  
The purpose of a story is to describe what about the system will be better for the user. Don't expand the scope of the story and lose sight of the user. This is a requirements document, not a design document.

No comments:

Post a Comment