Specifications Best Practice
We've all come across idea before. If the quality of your input is bad, then the quality of the output is likely to be poor too.
Think about this idea for a moment, and wonder what happens if the input is not something that you control. What if somebody else gave you the garbage input? What does that do to your process?
What would happen, for example, if you tried to assemble some flat-pack furniture, but the instructions skipped a few things along the way or were simply wrong because the shop had forgotten to fix them?
Well, you can probably imagine that the process becomes much slower and more painful than required, and the shop needs to hire people to be on the phone as customers attempt to assemble their wardrobes.
Garbage in, garbage out (and a lot of pain for everyone involved).
The same principle applies to API connectivity. We consistently see specifications that are incomplete, that have (sometimes quite obvious) errors and specifications which either assume too much or too little.
Faced with those as inputs, is it any surprise that the task of connecting to APIs takes too long, is difficult and is painful? Or that your team needs to spend so much time on the phone hand-holding customers through it?
My key message here is not to point the finger, but simply to highlight the fact that if you want a good outcome (fast connection, minimal assistance), then you must invest in the input to that process - your specs.
We know getting a specification right is hard. There is precious little in the way of examples or best practice. There is no effective forum to ask questions (and perhaps your boss wouldn't let you use it anyway). The complexity of your internal systems is big, and for brokers supporting customisations, this combination can be all-consuming.
But you can't give up! Because giving up is accepting that you will be feeding garbage into your customers' process, and therefore you are accepting that you will receive garbage in return.
So next time you hear someone frustrated because a client apparently didn't read the manual, turn it into a review of your documentation. And ask yourself whether there was anything else you could have done to change that outcome.