Why you should invest in machine-readable API documentation

One of the most common hurdles we come across when trying to influence positive change is a firm’s desire to innovate in order to create efficiency.

And you might be thinking, “Well, yes, but why is that a hurdle?”

“Efficiency” is our bright, shiny future. Efficiency affords better productivity, greater automation, better customer service and – ultimately – better commercials. But while most firms can see the clear benefits of this future vision, many struggle to find the time and resources needed to take the steps today get to that brighter tomorrow.

We often talk about “innovation” as a key cultural trait of market-leading firms. In the world of FIX integration and connectivity, innovation is taking manual, time-consuming tasks and processes and creating efficiency through automation.

This conversation always leads us back to one key element in our equation – machine-readable documentation. In order to innovate and improve efficiency, we need that critical component of machine-readable documentation. It isn’t a “nice-to-have”, nor is it just some modern, online equivalent of something that has always been fine in a PDF – it’s the foundation necessary to build, test, and conform in a more efficient way.

And so the challenge we find in helping firms improve their efficiency is directly tied to the availability of machine-readable documentation.

Innovating specifications is, therefore, a necessary first step in gaining the benefits of efficiency that firms so clearly understand.

But what does innovating specifications really mean?

It’s always very surprising to me when I talk to firms about moving to electronic specs that their very first idea is to try to derive electronic specifications from logs.

Perhaps it has something to do with the fact that logs are plentiful and freely available or that querying logs seems like a better (or a more interesting) use of time than getting around to correcting that Word document collecting dust in the corner.
But what does it say about the Word document you are handing out to prospects to code against if you aren’t willing to use it internally as a starting point for machine-readable specs? If it isn’t good enough for you, then should be handing it out to customers at all?

Some brokers and software vendors will say “ah yes, but there are lots of customer-specific transformations which means that there really is no single spec”. This is, of course, an entirely valid point. But those customer-specific transformations are already captured and encoded in XML or other config files somewhere. So why not consider using those to understand client differences instead of reverting back to logs? What does that say about the accuracy or completeness of those XML files?

Ultimately, we don’t see innovation as ditching our Word & XML files and simply trying to build specs from logs. As we’ve argued above, this is tantamount to acknowledging that your Word & XML files were inaccurate or incomplete in the first place and should therefore not be trusted.
Rebuilding from logs has the additional limitation that it can never generate the human-readable elements of API documentation — it can only list out messages, fields and values that have been observed. It can’t describe them in functional or business terms. This means that you actually decrease efficiency over time by not removing the need for extra human-readable documentation — you’ve just doubled the number of documentations you have.

So what is a better way? Innovation is all about taking something that exists and making it more usable through iterative improvements.

As a first step, we can take our Word specification and convert it into something more structured and machine-readable. We are changing the form but not the fact. We keep all of the human-readable elements that you’ve invested time documenting but start to unlock the content to boost efficiency.

Now that we have a foundation in place, we can use logs to test whether that documentation is accurate or not, and iteratively correct that places where it is found to be wrong. This way we use innovation to help us to identify and drive out problems, improving the quality of our documentation and boosting efficiency as we go.

And all of those customer-specific quirks? All of those will be flushed out in this validation step too. Not only will you be able to validate that they are all described accurately, but you will also be able to see which ones clients are actually using in practice.

We do of course appreciate that developing machine-readable documentation is a multi-step journey, and the fact of the matter is that firms often struggle to find the time required to take that first step because of the perceived scale of the project to consolidate, refine, and digitise specs. Having helped many firms go through this innovation cycle, however, we know first-hand that the end goal of automation and efficiency is achievable, and it is much closer than you might think.

1. Presentation

We appreciate that specs are more than technical documents. When bringing a new customer onboard you want your outward-facing brand to be strong and consistent. But, brand perception is far more than a logo and colours. If you, as a customer, received a PDF document, would you really think this is the most innovative way to distribute a spec?

Digital specs are structured, created, and customised to benefit both internal and external requirements. They are both machine-readable, and human-readable, enabling automated processes to be driven by them, whilst customers continue to interact with them in plain English.

If the challenges of presentation are a stumbling block, our Cloud Specifications tooling provides both digital creation and management, and human-readable, branded PDF exports.

2. Management

Specs created in Word are like writing a book using a typewriter. They both look nicely presented, but beyond revisions and amendments, their functional use ends there and then.

Managing specs then becomes a matter of organising multiple files, without any relation to one another (i.e. you can’t link documents as versions in Word), which inevitably leads to confusion and a lack of clarity over version control.

If time is wasted on the basics of file management, efficiency and automation is pretty much impossible.

Digital specs can be managed by versions, with inline version comparison, and saved in a centralized repository. This affords functionality like multi-team collaboration and digital distribution.

3. Distribution

Email as a tool will continue to be our primary method of digital communication. But when it comes to distributing specifications, as soon as you press send you lose control of who has access to that document, for an unknown period of time. You’ve essentially sent a document out into the universe, with no way of getting it back.

We know that firms have a desire to keep better track of who has access to each spec. But this is impossible without centrally-distributed digital specs.

By innovating your specifications and investing in the time to upgrade to digital specs, distribution becomes infinitely more manageable and transparent. Not only will this save you time, and therefore create efficiency, but open up scope to build automated processes that essentially extend the functionality of your documentation.

4. Extension

Imagine you have an API release and you need to articulate the change to all of your customers. One option is to send them an updated spec will all the information they require, but also 98% of which will be irrelevant.

With machine-readable documentation, you could work out which customers use which pieces of functionality, and therefore which would be affected by a new release.

So rather than sending full documentation to every customer and leaving it up to them to interpret, and then inevitably correspond and clarify with you what the changes are, you could only distribute the specific changes to the specific customers that would actually be affected.

When managing specs, a well-structured, machine-readable document afford additional functionality, such as capturing example messages, that can enrich your spec, maintaining iteration and avoiding specs become out of date.

So, by investing in innovation, your spec becomes a tool to extend functionality, create efficiency, and provide better customer service.

We’ve been developing digital specifications for the best part of a decade. We are uniquely placed to help firms overcome legacy documentation, and create positive change by managing specs in a more efficient way.

If firms are willing to invest in the time to innovate, accepting uncertainty and change, then they can reap the benefits of more efficient, automated processes.

Talk to us about your current documentation, what you are looking to achieve, and the current pain-points. Chances are we will have experienced them before and can help you take a positive step forward.