"Jim is a tool, Donna is a database" - designing good interfaces through roleplay

For a while now I have been trying to find a way of describing to those around me the mental process that goes into designing good software interfaces, APIs, web services or SOA components. And now I have found a good analogy I wanted to share it.

The basic idea breaks down into the following stages:

• Having reached a degree of business knowledge you start by trying a first cut of the grouping of operations into interfaces.


• Next, you give each interface a person's name and one that has nothing to do with anyone you know.


• Then you build a human character around the persons name, based on the type of operations they carry out and their degree of responsibility for the underlying business purpose.


• Having done that you can start to refine your interfaces based on imagining a person in a role, doing the kind of operations you require. And that is when the human aspect comes into its own.

Take for example a B2B system, there you might have Lucy who speaks good XML and will happily go out of the office to meet clients, and Nigel who has a lot of work to do in his backroom office, normally only speaks Cobol and goes home at 6pm every day.

By imagining your interfaces as people you can assign them behaviour and apply common sense to that behaviour. It allows stakeholders to be able to discuss what is in each persons job description and whether it is efficient for them to perform various tasks.

So in our example B2B system, if a new customer needs an account number - then you would much rather they deal with Lucy than Nigel, but Nigel is the one with the master list of account numbers. So you have a compromise to make and decisions to be take, you might want to install an ESB telephone so that Lucy can ring Nigel from her mobile to get the number or Lucy takes a new account number before leaving to visit any potential new customer, or even introduce James as a middle man.

I find that it makes spotting mistakes on an interface straightforward. If Jess your office post boy had been assigned operations that involved any degree of business knowledge then there is obviously something wrong, and similarly wrong would be if the CEO had to deliver his own post. From experience this technique works better in higher level interfaces than the programming language level, because the language level is far mor abstract and it is harder to assign human characteristics.