How to Communicate with Software Developers

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.

Telling Good Stories

Estimating the time it will take to make a software feature can be quite a challenge.  In order to have a reasonable discussion about how long a feature will take, we really need to have a reasonable idea about what the feature is.  Good estimates depend on good software descriptions.

My favorite way to describe software, for the purpose of estimating, is to develop “user stories.”  User stories are short phrases that describe a behavior that the software needs to have.  I have used two different ways of writing stories that seem to work well for me, so I’m pretty sure there are more than I describe here.

I first learned about defining a software product using stories from the book “Extreme Programming Explained: Embrace Change” by Kent Beck.  Later, more definition was added by Mike Cohn who wrote a whole book on user stories.  Cohn has a handy formula for writing them.

He suggests that you follow this form:

As a [user] I can [some behavior]

For example you could write:

“As an ATM customer I can request my current account balance.”

Another one might be:

“As an ATM customer I can enter my PIN before I am given access to my account.”

This form is very popular and I find that it works great.  Before I learned about the Cohn story form, I had developed a form myself.  I still like it because I think I am able to break stories into smaller pieces more naturally and it has a cool side effect.

Simply finish this statement:

“I will know that progress has been made when …”

What you write after this statement is usually a great user story.  The Cohn form fits this method as well.  I also found a similarity with the results of my form and the development of a “User Manual”.  The sum of all of the stories could reasonably become the product user manual.  Check out these three stories:

  • I will know that progress has been made when the software provides a place for the ATM user to enter their PIN.
  • I will know that progress has been made when there is a way for a user to ask for their account balance.
  • I know that that progress has been made when the software provides a way for an ATM user to print their account balance.

Now listen to them without the “I will know…”part:

  • The software provides a place for an ATM user to enter their PIN.
  • There is a way for a user to ask for their account balance.
  • The software provides a way for an ATM user to print their account balance.

Notice that this sounds a lot like a user manual.  Steve McConnell in his book: “Software Project Survival Guide” describes a way in which user manuals can be used as requirements documentation.  I really believe that he was on to something when he wrote that.

The best stories are isolated, meaning they don’t depend on any other story.  This may seem to be too difficult at first, but it is actually quite possible.  Don’t give up on making great stories. Using practices like this can help to make it easier.