A long time ago I used to do production support as part of my role (I was a Unix administrator/DBA/system analyst).
In those days requirements were really easy for me: people would come to my desk and ask for something, or they would email me or maybe even leave a scribbled note on my desk. There were no standard formats, no formality and (usually) no problems.
But even back then I had to work with vendors and sometimes that was when the trouble started. Some were happy with my “give me a call” approach to requirements, while others required a ticket and some even required a complicated work request form.
Now days, some production support teams are more professional that I was and they actually have real requirements or (if they are agile) stories. And most of them seem to be flooded with vendors.
So, do stories work with vendors? The obvious answer is YES. For example, if you receive a story in the following format then it should work for you and also for your vendor:
- As a coffee club member I want to be able to see a list of future coffee appreciation classes so that I can enrol in those that look interesting.
But what about complaints and bugs?
- As a coffee club member I don’t want to have my name spelled incorrectly because it is really annoying me.
I guess that works, but it is not how the user will raise the request. They are more likely to say “you got my name wrong”. We would then ask “what should it be” and then just capture the requirement to “for member 1234, please change the surname from Jonnes to Jones”.
That would work OK. But when there are multiple vendors all connecting different pieces of the puzzle then things can unravel surprisingly quickly.
For example, if you want a list of upcoming coffee appreciation classes, but you have outsourced the CMS to Kingcorp international (not a real company) and you have got need to link the classes to your existing database, built by the internal team, then you might end up with:
- As a coffee club member I want ….
- As the CMS, I want the cafelate database to provide me with data in an xml feed so I can send the information needed to the screen so the coffee club member can ….
- And so on.
But rather than butchering your stories so that you can use them, why not only use them where they are useful. Here is my starter kit for stories and other formats that work well with multiple vendors and teams.
Each tool is designed to either clarify the value you are trying to create for your customers, or remove the ambiguity involved in what you are asking for or both.
| Purpose | Tool | Value to you and your vendor | Not good for |
| Define the problem you want to solve | Problem statement | Creates a context for the problem being solved | Detailed specs for the vendor to work with |
| Define how the user will use or benefit from the system | User story or use case | Let’s the vendor understand what the user really wants | Backend systems |
| Define what each system does | Old school functional requirement | Clarity about what a specific system should do | Sending to vendors without the context from other approaches |
| Define how you will test it | Scenario test (use case)Acceptance tests | Tells the vendor what you will test | Working with evil vendors who insist that anything you don’t specify is out of scope. For these vendors I recommend a termination letter. |
| Getting what you actually want | Talking | Coming to a common understanding of all the above | Vendors and clients with inconsistent tact filters |
For reference, this is how you use each tool:
Problem statements and focussing questions are contained in this article. They are essentially an overall statement of what you are trying to achieve.
Use cases and stories
Use cases are roughly described in this article and you can also google the term to find a lot of information on them.
User stories are all the rage in agile circles. They are essentially a summary what you want, who actually wants it and why. So the standard wording is this
- As (a type of user) I want (something) So that (the reason or benefit I get).
Functional requirements
These are statements of what you want a particular system to do. They are described in this article and might follow this format
- (when something happens) (the system )shall (do something) (if this condition is true)
They work best when complimented by non-functional requirements (the qualities you want like user friendly or reliable). So you might use the FAB format I described in a previous article.
Acceptance tests
Acceptance tests actually list the conditions you will test for. The most common format at the moment seems to be “given- when-then”.
- Given (an existing thing is true);
- When (something happens);
- Then (this is what should happen).
Talking
There are several international standards for talking. I usually use English with Good Manners, but there are many other standards available.
Talking to your vendor still seems to be the best approach to me, even if complimented and clarified by the other tools above.
The only short-coming that talking has is that it does not work well when “nerds” and “business people” have different tact filters (see here http://www.mit.edu/~jcb/tact.html). This occurs when you are talking to your account manager but you are not letting your techo’s talk to their techos directly. Problems get solved and solutions get improved whenever you let the people in each team talk directly.
An example:
| Problem statement | How can we provide members of the coffee club with the ability to book coffee appreciation classes so that they can learn more about fine coffees (and pay us lots of cash). |
| Stories | As a coffee club member I want to view upcoming classes so I can choose classes that would interest meAs a coffee club member I want to be able to book for an upcoming class so I can attend classes in my area
As a barista I want to be able to publish and edit upcoming classes so that they can be seen by members |
| Requirement | The coffee club database shall store data on upcoming classesThe coffee club database shall store booking details for members who have booked a class
When the barista creates a course the outsourced CMS will publish the course on the café’s website for members to view When a class is full the outsourced CMS will post a label on the class to identify it as sold out |
| Acceptance | Given a class is full when the member tries to book then the member will be given an error message saying the class is fullGiven a member is viewing a class on the website, when the members clicks on the class headline then the member will be taken to the booking form
Given the member has been flagged as arrogant and annoying when the member clicks on the class headline then the member will be told “no class for you “ and will be provided with a link to an anger management class |
So what?
So that brings me to three quesitons:
Is there a best way to communicate your requirements with vendors on agile projects? Yes – stories and lots of conversations. Unless you are in different timezones then more elaboration around the testing will help – detailed use cases, acceptance tests or even old school requirements might help but rely mostly on the story and conversation. Unless you know more about your own team than I do, in which case common sense trumps advice from blogs.
So the same answer applies as per projects? Er – no. I actually think Prod support teams have a lot more one line requests to fix certain things out of t he blue. This would be fine if people asked for what they needed and production support teams understood what people asked for. But they don’t, so they should talk to their customers.
But when you deal with a vendor and requests come out of the blue it is worth reminding them of why you want something AND removing ambiguity. Conversations still win over anything else, but it is often worth using a more structured approach using tools like the ones I explained above in addition to the stories and conversations you are using.
I hope that is useful. Let me know if it works for your team.
James King 