A Lesson in Software Specifications, from Amelia Bedelia...

I read kids books a lot...to my kids of course. I've also been on a software/project management book reading kick lately, but more about that in a minute. Tonight I was reading Amelia Bedelia to my 4-year-old and it got me thinking about something else I had just read in Steve McConnell's Rapid Development this week.

So, for those who may not know, the Amelia Bedelia series is about Amelia Bedelia, a house maid for a wealthy family who always gets the instructions wrong because she uses a different meaning of the key words. So, when asked to 'trim the steak' and 'dress the chicken', she procedes to add bows and ribbons to the steak and put the chicken in baby clothes. She always saves herself from being fired by cooking something really great for her employers.

While reading the story (probably for the 60th time since we got it a couple years ago) I thought about how you can never just assume people will understand what you want them to do or what you are trying to describe to them. The more you can get out of your head and on paper the better. Amelia Bedelia is a great example, and another way to think of it is when there are not enough details and too much left up for the next person (let's say a software developer) to design on their own. When given this opportunity, the sky is the limit for how basic or extravagent the feature can be designed.

Steve McConnell gives a great example of this in his book Rapid Development. He discusses the importance of making clear goals, and uses an example of a specification that is silent on the question of whether to provide the user with the abiliy to control polymarker's sizes. The developer is left to answer that question and has any number of paths to take:

"1. Do not provide any control at all.

2. Set up the source code to be modified in one place for the whole set of polymarkers (that is, sizes of all polymarkers are set by a single named constant or preprcessor macro).

3. Set up the source code to be modified in one place, on a polymarker-by-polymarker basis, for a fixed number of polymarkers (that is, size of each polymarker - square, triangle and so on - is set by its own named constant or preprocessor macro). "

all the way up to..

"8. Allow for interactive, end-user modification of a single polymarker-size specification.

9. Allow for interactive, end-user modification of polymarker-size specifications, with one setting per polymarker, or a fixed number of polymarkers.

10. Allow for interactive, end user modification of a polymarker-size specifications, with one setting for polymarkerfor a dynamic number of polymarkers."

And you can just imagine the differences in development and testing time between option 1 and option 10. Unfortunately project teams can't cook killer brownies or lemon merengue pie to make up for overblown budget or to soothe angry clients or end users. So, learn from Amelia Bedelia and make sure that the software specifications include as much detail as possible. And save the great brownies for celebrating a sucessful launch!