Do FIX Documents HAVE To Be Bad?
I spend far more time thinking and talking about FIX documentation than… well pretty much anybody I’ve ever met.
Despite being an outwardly-boring subject that is just too easy to swat away with objections like “we haven’t updated our FIX documents in donkey’s years” or “we’ve probably already onboarded all of the main customers”, I keep being drawn back to it.
Why? Because I genuinely believe that most people have missed the point that documentation exists to help your customers connect to you faster and easier.
Poor Documentation Silently Limits Your Growth
Poor documentation leads directly to a confused developer, a slower, more-painful initial on-board (slower time-to-revenue), and it really limits your chances of getting them to add new functionality in the future. Put simply, poor documentation makes the whole process unpleasant from start to finish, for both parties.
So why don’t people do something about it?
Well, it’s just too easy to reach for a common excuse to push it off:
- It’s not clear who should update it (lack of ownership)
- I’m too busy with the day job
- Our service is so unique / complex, it can’t be made easier
- Limited pipeline of new customers demanding it
- …
I don’t doubt that many of these are valid considerations, but much like that New Year resolution to do more exercise, anything that is worthwhile in the long-run takes short-term effort!
Perhaps you are one of the enlightened ones who understand that there is something wrong in your documentation, but you don’t have a clear picture just yet. If so, then read on!
What Does Good Documentation Look Like?
If you’ve ever read looked at non-FIX API documentation, then you might already have an understanding of what “good” looks like. If you haven’t, then take a quick look at the Stripe API documentation — it’s often cited as the “gold standard” for REST APIs.
Obviously, it is a web page and not a PDF. Obviously, it’s attractive to read, and I can immediately see that it will help me understand both the concepts of the API and the nuts-and-bolts of how to integrate with it. There are ample examples and code snippets everywhere to kick-start my development, and even help videos scattered throughout so I can deep-dive on topics if needed.
The developer experience is so much better than receiving a massive PDF via email filled with jargon that people have avoided updating for years, they are barely comparable.
That is what we should be aiming for with FIX documentation.
OK. Let’s Answer Those Obvious Questions…
“Hang on though Chris, Stripe will have armies of technical writers and web designers to keep that up-to-date, and I’ve got a day-job to do…”
Yes - you are right. It does take effort, and it does take different skills to those that you might have on your team today. There are firms that you can partner with, however, who can assist with those areas (allowing you to remain focused on the day job), but the first step is to recognise the need for such a step. Are you there yet?
“Isn’t this what formats like FIX Orchestra, FIXatdl and FinSpec were supposed to do? Can’t I just give someone that and not have to write documentation?”
There is a great blog article by Julia Siedman of Stoplight in which she describes the importance of mixing both the “ingredients” of an API (messages, tags, values) with practical guides to help readers really understand how everything fits together. Julia makes a really important point here, and it is one that is often overlooked.
FIX Orchestra, FIXatdl and — to a lesser-extent — FinSpec all start with the goal of wrestling the ingredients of an API into a structured form. They move messages, fields and values from free-form Word tables into something structured, thus allowing them to become machine-readable. Unless humans are removed from the connectivity process completely (which I do not believe they can), then there is a continued need for guides to be read by humans.
It is the creation and maintenance of this combined knowledge base that is really required here, which goes beyond the question of technical format.
“I know a bit of markdown, and so I can just convert my Word doc to markdown and plug it into some sort of open-source library for display. Easy!”
Really?
What about authentication of users? Where are you going to host that? What about branding and version control? What happens when you want to add downloadable assets? What happens when you leave and maintenance passes to colleagues who aren’t as comfortable with Markdown? How is the Markdown related to other assets, or is it yet another separate asset to be maintained? What happens when you want multi-page documentation that covers multiple APIs?
Clearly, this isn’t a simple job either technically or practically. But the news gets even worse I’m afraid. You see, if you were actually able to turn your 100-page PDF into Markdown and get it online, the simple truth is that (in all likelihood) it still wouldn’t be as good or useful as Stripe’s.
Why? Because decades of Word / PDF use has sub-consciously influenced the way your documentation is structured today, and the sort of rich, online API documentation that Stripe offers doesn’t work like that. The challenge is to both re-format, re-structure and expand the content to give a better developer experience.
Don’t worry though —there are people who can help!
Why Now?
I haven’t pulled any punches in this article! I’ve laid out the argument as clearly as I can, highlighted the pitfalls along the way, and I’ve shown you a practical example of what good documentation could look like.
If you have read this far, then I’m thrilled that you agree this topic is important enough to see past all of the “easy” objections. But now we arrive at the toughest question of all — why now?
I’ve spent my whole career in financial services, and so I know that all-too-often we find ourselves in firms which fall into one of two camps; either there simply isn’t the budget or headcount to take on more work, or there are too many people which makes decision-making too slow. In both situations, non-production and non-revenue-generating projects are drop like a stone to the bottom of the priority queue. There they remain there until the day that something changes and they suddenly become urgent and strategic. Stress-levels rise and everybody rushes around to do “whatever it takes” to make it happen.
What are the potential triggers for such a priority change?
- Management realize that FIX is just another API. The global trend for API documentation could not be any clearer or predictable — it’s all online, and it all looks like Stripe. It is simply a matter of time before management start asking why your FIX API is not documented in the same way. Indeed, most Crypto trading platforms are already doing exactly this.
- Your company invests in a customer portal. As companies respond to customer demand for self-service, and seek to automate their own workflows, more firms will move towards offering self-service portals. Financial services firms of all sizes do not typically have in-house web developers — it is not something they’ve ever needed before — and may struggle with this transition. API documentation is a significant portion of the content to be delivered through such a portal.
- Your competitors start doing it. This is always the biggest motivator; a prospect mentions how they saw something cool from your competitor, or they win an award, and the next day it is added to your annual objectives. You know the way that goes.
- Something goes wrong. What would happen if a production issue was traced back to inaccurate documentation? Or a high-profile prospect doesn’t go live, because they give up with your documentation? Both have the potential to trigger a laser-focus on improved documentation and process (although I accept that it is more likely to be a review-style project than fundamental re-write).
To be clear, I don’t think this shift will ever happen as a big-bang change driven either by regulation or an industry-wide initiative such as the way Open Banking is quickly re-shaping transaction banking. No, I believe this is more likely to be a slower, commercially-driven transition that will happen over time and follow the classic technology adoption curve.
The question is therefore not if you will make this transition, but rather when it will make it. Do you want to be an innovator or a laggard?
