If you are a project stakeholder and you have software that needs to be made, you might discover that it can be difficult to communicate your needs to software developers.  You may believe that you have communicated your desires, only later to discover that the developers have no idea what you mean.  So, how do you deal with this issue?  How do you communicate what you need to have done?

The most adequate software requirements I have seen, are test scenarios.  When these are provided before software is written, it gives a developer most of what they need to know to start working on the software.

Making test scenarios as requirements documentation takes serious dedication on the part of the customer representatives, though.  It requires that they go beyond providing a few sentences about the software.  They actually must pretend that they are using it.  It requires an adequate set of test data and a good imagination.  You must detail the actual steps you would go through and what you expect to see.  These are the procedures that will prove that the system is actually working in the end.

The basic framework for these scenarios is actually very simple.  They follow a three step pattern:

1. Set up the starting conditions
2. Perform some work
3. Check for expected results

To write these down, you can use a pattern like this:

1. Given a specific situation
2. When something is done with the software
3. Then some new situation is the result

I have come to call this pattern: “Given – When – Then.”  It has a formal name as well.  These descriptions are what we call “finite state machines” in software engineering.  A computer program can be defined as a set of these.  The great thing about them is that they don’t require a degree in computer science in order to make.  The only difficulty is that they take time, energy and attention to detail.

When you are first learning how to write these, I suggest that you start each step with the “Given,” “When” or “Then.”  Here’s an example:

1. Given a user that has a bank account and has already put their ATM card into the ATM and used their pin to access their account.
2. When the user requests a balance.
3. Then the ATM shows the user’s balance to the user.

It may look easy at first, but it usually becomes evident after you start writing these down, that things have not been completely thought through.  For instance, notice that in the given part of this ATM scenario, you haven’t really described how the ATM should use the PIN yet or when the card should be taken.  Then there’s the possible fraud cases.  You have to know when to deny access too.  After you get started, you may feel like it’s just too hard, but don’t give up.  What is actually happening, is that you are flushing out issues before a software engineer is employed.  This hard work pays huge dividends.  It makes it possible to communicate with software engineers in a way they actually understand.

Although every detail that is important should be described, not every Given-When-Then has to be done before software development begins.  This is one of the biggest benefits of agile practices.  It’s important that developers use a method of development that will support changes to requirements, though.   Test-driven development and the creation of automated tests for your scenarios make that possible.

You might be thinking that you really should write down all the test scenarios before you have a developer start working.  The problem is that we usually forget important scenarios and have to add them later anyway.  It’s good to detail as many as you can and then prioritize them.  It’s usually the focus on priority that will benefit you more than completeness.

So, I challenge you to try this with a single test scenario.  Write out your scenario using the Given-When-Then style and take it to a software developer.  You will probably be amazed at how fast they understand what you’re asking for.