API Specifications Best Practice
Over my years at FixSpec, I've talked to well over a hundred people who either read or write API specifications as part of their day job. And I can summarise all of their feedback in a single word.
How do writers feel about the quality of their own specs? Blah.
What about the job of updating them? Blah.
How do developers rate the quality and accuracy of the average spec they receive? Blah.
The fact is that as an industry, we have sleep-walked into a situation where our expectations for API documents are really quite low. It doesn't take much to shine — just make it accurate, write it in plain English, and maybe give a few examples.
Talk to most developers in fact and - after a little cajoling - they typically admit that they don't really read them at all, but instead merely skim through them. The problem is most acute in FIX I find, where developers simply flick through to find the FIX version number and then start firing in canned messages.
This nonchalance leaves some spec authors wondering why they should prioritise investing energy in specs if nobody actually reads them and their helpdesks have to keep answering the same basic question again and again and again. So what’s the answer? Throw in the towel and not bother writing or updating specs anymore? Of course not - that would be absurd!
The goal should be to make your spec as complete and accurate as possible so that you can (politely) keep referring customers back to it and let them help themselves. The secret to success here is one very important but commonly-overlooked fact - developers want to read the documentation in a different way to how you want to write it.
To understand this, put yourselves in the shoes of a developer in a customer or vendor. You don’t know how all of your funky functionality works, and you don’t know what any of your three-letter acronyms mean. You just have the PDF and your manager has told you to code to it urgently. So what would you like to see? Examples always help. Maybe a glossary of terms. If it is a FIX-based interface, where do you deviate from FIX standards or other FIX interfaces that they may know or understand? If it is a non-FIX interface, describe how to maintain a connection and form messages. Are there sections of your spec that are incomplete, incorrect or simply too boring to read?
Not sure what developers may want? Here are some simple suggestions to find out:
This exercise should highlight simple, quick changes to your spec that we believe will more than pay for themselves in terms of time saved later answering the same question again and again - you just need to trust the process and do it.
And remember, if the average specification is just "blah" you should quickly see tangible benefits from a small investment. Let us know how it goes.
PS. Some readers may question whether moving to electronic specifications is the answer here. We are fans of moving to electronic specs for a host of reasons - more on that later - but the fact is that unless you invest in the accuracy and completeness of existing specs, then it is likely that you will end up with a poor electronic spec. So we see the tidy-up process described here as a foundation for migrating to electronic specs in the future.