Interface Documentation

Documentation is a key element of interfaces even if it is something many people try to avoid as much as possible due to the effort to keep it in sync with the implementation of an interface. This is because the vast majority of firms still rely on a largely manual process to compile specifications and user manuals for interfaces. For example,

  • the developer adds another field to a message, maybe due to a business requirement that was forgotten or simply a change in the design of the interface, e.g. using two fields instead of one to represent a certain business functionality;
  • the business analyst may have to update the specification unless company policy does not allow the change of formally approved documents (or requires to repeat the approval process);
  • the tester has to adjust the test cases and the technical writer has to change the user manual by adding the new field.

Publically available user manuals are usually provided more than once during the development of a new version of an interface to give customers more time to enhance their application that use the interface. This simply means that the situation is futher aggravated and the manual creation of interface documents becomes a cost factor and a potential target for savings.

FIXdom can help you to introduce a high level of automation into your related processes. This starts with a single electronic representation of your interface that serves as a master for different types of output, i.e. source code, test cases and documentation. When it comes to interfaces, source code and documentation have similar requirements in terms of an audit trail of changes. The usage of a source code repository like GitHub or SVN not only allows multiple developers to collaborate on the same software, it also makes sure that any change, even the smallest one, is automatically captured together with information about the author and the time of change. After all, the reason for a software bug can be a minimal change that has some weird side effect. The developer may not remember his change but the audit trail will. A typo in a user manual is obviously less critical but interface documents typically include message layouts and a list of valid values for a field. These need to be just as exact as source code and there may be more than one person working on the same document. Using a word processor application with track changes is highly inefficient for larger interface documents.

FIXdom can help you to transition from a manual process to an automated one by moving to markdown as a simple and generic format for the raw information. This allows separating content from its rendering (visualisation) and storing content just like source code in a repository and benefitting from its automatic tracking of changes. Using an open source tool such as Pandoc, the markdown format can then automatically be converted to docx/pdf documents and html pages that follow the layouts of your company documents and website.