Best Practice Onboarding Efficiency Series
Let's state some facts up front:
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:
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:
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:
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".
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.
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;
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.