Skip to main content

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.


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.


Popular posts from this blog

Database dump with Java

I need to update a database that is created by PHP. The problem is that I am not a PHP coder, but a Java coder, and I need to use some other Java libraries to get the job done. So how can find out exactly which tables to update and how? It would take me weeks to search the PHP code, and I still wouldn't be sure if I got it right.

The first step is to install a clean application on my computer. There is no user data in the database, so if I perform commands like creating a user etc in the web application, I can look at what changed in the database. I'm sure that could be done in MySQL, but I'm not an expert on that either. When the only tool you have is a hammer, everything looks like a nail. So, I'll use Java for that to.

So, I wrote a small Java application that produces exactly the output that I need. It reads metadata from the database to find all tables and columns, lists that metadata and the content of all the rows.

Here it is:import;

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…

Examples and Objects

The most successful and fun project I have been part of developed a network simulator for operator training. We had a great team and freedom to work how we wanted, but another key to success was the domain model. The analyst drew object diagrams to explain to the programmers and testers how a network topology could be, for instance like this:

This may look simple, but these diagrams explained a lot to us. We used them to discuss what should happen in different scenarios, such as what should happen when a Trunk is connected to another Port. Then we implemented these scenarios as unit tests. This resulted in a robust implementation with few bugs.

But in most projects, we don't have anything like this. In one project I spent several days trying to understand how a trading system worked. I had the domain model and database schema, but it was not clear when these objects were created, updated and deleted in the database. I read thousands of lines of code and run the program in a debu…