Let’s state some facts up front:

  1. Writing specifications isn’t fun. It’s boring and thankless, especially when it often feels as if customers don’t bother to read them.
  2. There’s no “best practice” document to learn from, and therefore you are on your own to copy/paste/adjust from something else.
  3. Keeping specs up to date is the last thing teams want to do when faced with a tsunami of other high-priority issues.

Sometimes writing and maintaining documentation can feel pointless, especially for banks which routinely accommodate customers requests to either default or override their standard API messages. After a while, the internal perception becomes that the “formal” FIX specification has little value; as something that simply represents the starting point for discussion as opposed to a firm document.

FixSpec doesn’t dispute any of these facts, we commiserate with firms faced with them.

We want to help make things better.

The one thing we know with 100% certainty, is that the answer is NOT to throw in the towel and give up, or to adopt the unhelpful approach of “we are FIX compliant, so just send us what you want”.

The answer is to change the documentation itself, as well as the way it is produced and used. Explicitly, we believe that documentation should be:

  1. easier to maintain and share,
  2. more useful for the reader, and
  3. update more frequently to iteratively improve.

Before we get onto some practical tips, we need to discuss tooling. Buying a bespoke API specification editor is perhaps something that your firm has never considered – why bother when Microsoft Word is already on everyone’s computer right? A well-designed specification editor can, however, solve a variety of broader issues around maintaining API documentation, such as:

  1. A centralised database to ensure everybody internally has access to the latest possible image (and can work on it collaboratively),
  2. Embedded best practice and suggestions for layout and completeness,
  3. Tooling to help identify inconsistencies or errors in the specification,
  4. Easy to version, edit and difference, reducing the barrier to issuing new updates and understanding change between them,
  5. Assist with customer notifications when new spec versions are published,
  6. Auto-generation of various export formats such as QuickFIX XML without the requirement for hand-coding, and
  7. Offer an API for other applications to retrieve specification information in a machine-readable format.

Tooling aside, however, here are some important items to consider when writing good API documentation:

1) Be More Verbose In Change History

Your readers will fall into two broad groups; those that have never seen your API before, and those who have received this as an update. Our first tip is simply not to forget the second group!

All API specifications are written as a “snapshot” of the API as of a point in time – this is how it works today. It is important to do this of course, but comparing one 80+ page PDF with a second 80+ page PDF is neither easy nor pleasant. So try to make understanding the differences easier for readers who are looking at an update to your spec. Ideas may include:

  1. Be far more verbose in your change history. Don’t try to cram everything into a small table in the front – consider writing a longer “Upgrade” section to give a more detailed description of what has changed from one version to another from both a technical and business perspective. Ideally, this would include an impact indicator such as “backwards compatible” or “new enhancement”.
  2. Consider leaving track-changes visible in the PDF document send to customers – it will help them identify everything that has changed. You will need to use your judgement here though, as track changes can be confusing in some cases.
  3. Consider adding additional (version-specific) notes in spec versions to add extra detail. Using shaded boxes is a good way of making these stand out as special notes.

2) Be Honest & Clear About Non-Standard

Protocols such as FIX are very good in that they allow brokers and exchanges to extend the standards, creating custom fields, enumerations and even messages if they like.

Understanding the key differences between your specific API implementation and the “standard” is one of the key tasks of a developer. So you need to be up-front and clear about it – this is not a time to try to bury it in your document, as it will only come back to cause more headaches later.

3) Think About Reader’s Experience Level

This is one of the most complex aspects of writing good API documentation – how much knowledge should you assume about your readers?

This can be a tricky area to get right, but here are some good rules of thumb;

  • Keep track of customer questions during onboarding. If the same question comes back more than twice then you should consider whether your documentation could either be clearer on that point or assumes knowledge that your reader doesn’t have.
  • If the protocol follows a well-understood standard such as FIX, then it is reasonable to assume quite a high level of knowledge, and the focus should be on understanding the difference against the standard.
  • If you want to assume that your readership has little to no experience in your API (perhaps because you have an entirely bespoke protocol), then consider splitting the document up into volumes, detailing slower-moving aspects such as connectivity versus faster-moving application messages.
  • Consider how best to use appendices to make reference data more accessible and outside of the core document itself.

4) Explain Functional Context And Workflow

One of the greatest challenges a developer faces, it to understand the functional context of a particular technical message. Developers will want to know when they can expect to send or receive a message, and whether the content of the message may change depending on the context.

[Shameless product plug: Our SpecServer product offers unique functional views – a way of easily describing and viewing a message within a given business context. It’s great at allowing firms to present clean, concise, context-specific descriptions of order types or business messages without all of the “if-then” statements which make algo specs so confusing].

Describing there API workflows and message context in a way that is both complete and succinct can be very hard. Some firms use UML workflow diagrams to summarise this; ideally, the diagrams would contain interactive hyperlinks or references to allow them to skip directly to related messages.

5) Examples Speak A Thousand Words

Describing the theory is good, but providing message samples really are the best way of explaining the intended construction to customers.

This is also an area where paying attention to customer questions and feedback is useful – focus first on providing examples for the messages or structures where customers either ask frequent questions or often make mistakes during certification.

Finally, remember that investing time and energy in getting your API documentation right is time very well spent (even though it may not feel like it today!) Done correctly, it will remove confusion for your readers and let them develop faster and with fewer errors, thus accelerating your onboarding process.

If you are struggling with your documentation but don’t know where to start, then drop us a line. We would be happy to give you FREE, no-obligation feedback on how we would suggest making improvements.

If you would like to receive more tips on how to improve your onboarding process, then please subscribe to our Efficient Connectivity newsletter below.