Thursday, November 29, 2012

Writing Better Requirements with Examples and Screen Sketches

We were agile, we had a Scrum master, we had standup-meetings, we had unit tests, we worked iteratively and met the product owner regularly. We did everything right, except the requirements. When we were almost ready to launch, we suddenly understood that we had missed a critical piece of functionality; namely the complex pricing model. The product owner thought we knew how this should work, but we didn't. This was not a feature that could just be patched onto the application in the end, it took several weeks of restructuring. We might blame the product owner for not communicating this clearly, but we were the software professionals. It's our responsibility to find out what our customers want.


What could we have done to avoid this embarrassment? Should we have spent the first month of the project writing requirements? No, I don't think that's the solution. That might have helped, but it would have cost too much.

There is a much simpler thing we could have done. In one word: Examples. If we had given the product owner an example of how we would calculate the price early in the project, the product owner would immediately have pointed out the misunderstanding and explained how to calculate the price correctly. This would have enabled us to make a better plan and implement that feature effectively.

Examples is a way to write useful requirements without too much effort. They are easy to understand by all parties involved: Users, project managers, analysts, developers, UI designers and testers. Examples reduce misunderstanding and thereby reduce risk and save cost.

Another advantage of examples is that they can be tested automatically. This is not possible with traditional requirements specifications. Then, you first write the general requirements, then test specifications and perhaps try to automate the tests. But examples are tests, and if they are written in an adequate format, they can be used by testing tools. This saves manual work with testing, ensures that the implementation and specification are consistent, and helps developers to focus.

Screen sketches

What is the best format to write examples? What does the user understand best? The user interface, of course! That's why prototypes are so useful. To quote Jakob Nielsen:

Whatever you do, at least promise me this: Don't just implement feature requests from "user representatives" or "business analysts." The most common way to get usability wrong is to listen to what users say rather than actually watching what they do. Requirement specifications are always wrong. You must prototype the requirements quickly and show users something concrete to find out what they really need. (

A problem with prototypes is that they take a while to build. Writing requirements should be quick and easy so you can do it together in a workshop. Also, prototypes are not suitable for automatic testing.

Instead, we can specify examples as user interface sketches. This is not user interface design, but a user interface specification. The sketches don't need fancy widgets, it suffices with labels, text fields, tables, check boxes and selection boxes, so that input and output values can be displayed. At this stage, we only need to specify what the user can do, not how.

For instance, an abstract requirement like "The employees report worked hours every week," may seem obvious to the customer, but it leaves lot of room for interpretation. Instead, we can give a concrete example like this:

This example is much easier to understand than the abstract requirement. The customer can easily spot mistakes and fix them. For instance, the customer may point out that they can work on multiple projects at the same time and give a better example like this:

In my opinion, this is as clear as it gets. It reveals a lot of questions for further discussion, like who defines the projects, can the employees work on weekends, what happens if the employee works more or less than 40 hours in a week, etc. Discussing these questions with the customers before implementation can easily save an iteration or two in the project.

Tool support

Screen sketches are easy to read, but are they also easy to write and suitable for test automation? It is fairly easy to make a tool that lets you design screen sketches; either a GUI builder, or simply writing them in a text format. This data can then be used by a tool to test the application. I have started on such a tool where you can write wiki-like text and generate HTML pages with screen sketches. The examples can then be used for automatic testing. You can read more about the tool and try it here.


Examples are useful for communicating with customers, as specification for programmers and UI designers and as test specification for testers. Ideally, all these groups should discuss the examples in detail together with the customer and analyst before an iteration. The programmers will then have all the details they need, the testers will know what to test, the customers will get the right product, and everybody's happier.

Friday, November 23, 2012

The Future of Programming

The problem with abstractions

Programmers are experts in abstract thinking. To program is to generalize: A method is a general specification of different execution paths. A class is a general specification of objects. A superclass is a generalization of several classes.

Although our minds are capable of abstract thinking, concrete thinking is more natural, and concrete examples are the foundation for abstractions. For instance, how do you teach children what a car is? You don't give a definition like: 'A car is a wheeled motor vehicle used for transporting passengers.' Instead, you point at a car and say: 'Look, a car!' After seeing a few cars, the child understands what a car is.

Notice what I just did! I started with a general principle and then gave an example. Which part of the paragraph above is easier to understand, the first sentence (general) or the rest (example)?

Einstein said that examples is not another way to teach, it is the only way to teach. It is easier to start with a few examples and then generalize than the other way around. If you start with an abstract description, you will often try to comprehend it by visualizing an example in your head.

The problem with text

Another point is that children understand better what they see than what they hear. Or as they say, children do what you do, not what you say. This is not only true for children. We understand what we sense in fractions of a second, but words must be analyzed before they give meaning. This doesn't take long for simple sentences, but it can take hours, days or months to understand source code of any significant size. Some source code is actually incomprehensible and nobody dares to touch it.

What does this have to do with programming?

As programmers, we are highly skilled in abstract thinking and textual programming languages, but when the code becomes too complex, we try to comprehend it by imagining its behavior. And when it becomes too hard to imagine the actual execution by reading the abstract code, we log what happens or run the code in a debugger. Logs and debuggers are not abstract. They give concrete descriptions of what is actually happening. They give information on method calls, object instances and variable values. This concrete information is much easier to understand than the abstract code.

We can move programming closer to how the mind works by using examples as part of the implementation. Unit testing is one way to do this, because unit tests are examples of what the code can do. There is also a growing movement for using examples as requirements. This improves the communication between users, analysts, programmers and testers. These examples can be automatically tested to connect them to the code.

Objects are examples of classes

So what is the best way to specify examples? I think that the most effective formats are user interface sketches and objects. The user interface is the best way to explain the external behavior of a program, and objects can be used to describe the internal behavior. I am not talking about technical objects that is part of the infrastructure, but domain objects that the end user understands.

Objects can be specified as text, in tables or in diagrams. Diagrams are easiest to understand, but they can be cumbersome to draw and edit.

Here is an example of an object diagram:
It is pretty obvious what this means.

If Lars sells his car to John, the objects should be changed like this:
Alternatively, the same information can be specified in tables or as text.

Modeling examples as objects is an effective way to build a domain model. This makes the examples consistent with each other and helps to reveal details and missing functionality. They are great as specification for programmers, because they are specific and contain a lot of details. And they can be automatically tested easily.

Tool Support

I believe that using examples and objects is the future of programming because it is closer to how our mind works.

I have started on a tool where you can write a specification by examples with screen sketches and objects. The application is then implemented in Groovy; a dynamic language that runs on the Java platform. The tool can test the examples to verify the program. Read more about the tool and try it out here!

Stay posted!

Thursday, November 22, 2012

Object cases tool released

I just released our new tool. It supports specification by example, object modeling, automatic testing and implementation in Groovy. The tool is open source. Here it is.

Stay tuned!