Do People Read Your API Documents, Or Are They Just Decoration?
I was gifted a wonderful hardback book recently — Flight-Free Europe by Lonely Planet.
Those who know me personally will know that I made a decision a number of years ago to radically reduce the number of flights I take. I may have taken it to the extreme, unfortunately, and am now so evangelical about it that I often cross that thin line into finger-wagging lecturer.
Anyway… This article isn’t about my aggressive eco tendencies. It’s about the book and what happened it it.
It’s a wonderful book. Filed with great trip ideas. Beautiful enticing pictures. It’s weighty and just… well nice.
But the problem is that I never read it.
I took it out of the gift wrapping paper, put it on our coffee table, and at least six months went by before I picked it up again to flip through it.
And the analogy struck me between this personal experience and what I’m focused on in work. You see, I spend a large chunk of my time evangelising about API documentation and why my little niche — financial market trading connectivity — continue to send new customers 200-page PDF documents, only to discover that nobody ever reads them.
Well, the reason is exactly the same as my Travel Book.
Everybody forgets API documents also
Both are reference documents; the sort of thing you dip into when you are stuck. They NOT novels that I might read from cover-to-cover to avoid missing an important part of the story. Reference documents are the sort of thing where I dip in and out as required. I look things up, but I don’t read the whole thing.
You may have a stack of Lonely Planet books on your book shelf at home too — most people over the age of 30 normally do! These days though, they tend to serve as a souvenir or cherished memory of a trip you took long ago. But if you wanted to go back to those countries now, would you pick up that book? Probably not — you would go online.
My point here is that a bookshelf full of reference books today serves more as home decoration than a useful resource; we get our information online, trusting that it will be more up-to-date, complete and searchable than something printed years ago.
So if you are a trading firm who keeps asking why customers never pick up and read the PDF from a virtual “bookshelf” of such documents on your website, it might be time to ask yourself when the last time was you read a book on your coffee table.
I’d love to hear your thoughts on the state of API documentation in trading today — let me know in the comments.
PS. If you are want to know what happened to Lonely Planet, just look it up in the shelf full of encyclopedias that you still have at home. (Or maybe https://en.wikipedia.org/wiki/Lonely_Planet)
