All that she wants..

It’s now a month since I first learned about the concept of Specification by Example, and I thought it was time to incorporate the practices in my hobby project; making a portable shopping list for Android. As the developer I am, I boldly set up FitNesse on my computer and thought “Now I will write some GOOD specifications with examples”. But where to start? My attempts at writing examples showed me that I was describing ‘how’ the app worked, not ‘what’ it should do. Then I realized my first mistake. My focus was on automation and code validation, not on specification at all. I needed to push back and find out ‘Why’ I was making the app in the first place. 

At least this was easy since I had ‘ordered’ the app. The desired effect I wanted was to make the grocery shopping process easier for my family. We’ve tried other app’s on the market and none of them was good enough to get my wife to use them. So I needed an app that would meet my wife’s requirements for easy grocery shopping. Eager to succeed I started writing an effect map and wrote down everything I could think of that my wife would want in a grocery app. Feeling very clever I presented my findings to my wife, and she agreed that almost everything I had written where nice features she would like. This was no surprise, since I like to think I know my wife very well. Just to be sure I had covered everything I asked her if there were other things she could think of that would make grocery shopping easier. “No, I really don’t know what is possible to do with an app, so it is a bit difficult to say” she told me. It was clear she felt that her “duty” was done and wanted to talk about other things. But just as I had learned from the course, I insisted that anything would be welcome, even non-SW items. “Well”, she said, “I get a bit hindered since I need to hold my phone when shopping, it’s much easier to hold a small piece of paper..“

Then it struck me. I had just played out an all too common scenario from our industry. Gojko warned us several times of this in his course. It’s all too easy to focus on the system we want to make, so we forget what our stakeholders actually need. When being presented with a promise of a good application she liked my ideas. But any app I make won’t turn her phone into a piece of paper, which is what she actually wants.

Hidden moral of the story: 1) Push back to find the desired business effect. 2) Always collaborate with business users when deriving the features from the goals.

Daily introspection

Reflection is a key factor in the learning process and is essential when we try to systematically improve. There are a lot of different techniques for reflection depending on what you want to improve and whether you want to reflect individually or as a team. Although many recognize reflection as important, few actually take the time to reflect often and regularly. This is why I propose the simple technique ‘Daily introspection’.

The purpose of ‘Daily introspection’ is to establish a habit of thinking about what you do and how it affects your work and the world around you in general.

Daily introspection:

1. Create a reminder for when you would like to do your introspection (preferably morning).
2. Choose ONE tasks/issue from the previous day.
3. Write a few lines of why you think you did the right thing, or how you could have improved the situation.
4. Throw away what you write.

These steps should not take you more than 3-5 minutes, which is just short enough to not find excuses for being busy. If you don’t have 5 minutes a day for something, you don’t want to do it. To keep it this short it is important that you do not choose more than one or two issues. If you really need to reflect some more, tell yourself that this is an extraordinary reflection. Stick with the short reflection until you feel that you have established a habit.

Some of you will probably want to keep what you write as reference for later use. Maybe you want to look back and see what you have written a month or a year ago. Although this probably could give you some value, I advise strongly against it. To establish a habit by being consistent, you should aim for an easy flow. When you think you might read it at a later time, you will start to worry about how you write, which raises the bar for the technique as a whole. Besides, setting up a filing system for 365 reflections a year might discourage you.

If you try ‘Daily introspection’ I hope you will find this technique useful. I would love to hear your experience with introspections, and other techniques for making this a habit.

Specification by example

I attended a course on ”Specification by Example“ by Gojko Adzic, and he challenged everyone attending to write a summary of what we learned. Feel free to comment or give feedback if you have attended his course and have other perspectives of this, or if you see that I have misunderstood something. For those of you who are not familiar with Gojko’s work, I strongly recommend it. Check his site http://gojko.net.

Summary of Specification by example course

As I understand it, Specification by example is the process of creating requirement specifications using key examples from the business point of view to validate that the software is working as the business intended. The specifications are used as automatically run tests against the system and thus hold the Single version of truth. After deployment of the system these tests will also serve as Living Documentation of the system. As a developer I like to think of this as following TDD from the business point of view. (You might know it under other names as well.)

Setting up functional tests with tools like FitNess is not new to me. But a key point I got from the course is how to specify these tests in order to describe what the system should do and not how the system will do it. The latter is sadly the most usual mistake according to Gojko, and I realize I am one of those who have thoroughly misunderstood this. To see if you have captured what in your examples/tests you can use these criteria: 

1. You are using keywords from the examples to summarize them
2. You can’t summarize the examples in more simple terms.

Many of the guidelines for making good unit tests also apply to good specifications with examples, i.e. Keep them simple, Self explanatory, Easy to read for intended audience (business people in this case). An important lesson from the course is to push complexity into the gluecode layer. In other words, everything you need to setup and start test, such as inserting data into database should be handled by gluecode. If I understand this correctly this means that the speed of the tests are important, but not as important as keeping your tests clean and simple!

Achieving Living documentation is not something most organizations do in a flash. Gojko presents some process patterns one can implement to gradually get to Living documentation. These patterns are

·         identifying Desired business effect

·         Deriving scope from the business goals when the team is ready to implement more functionality. 

·         Identify Scope using User stories or Use Case

·         Collaborate to find Key examples

·         Refine into Specification with examples

·         Automate to get Executable specification

·         Validate frequently and evolve into Living Documentation