Minimal integration 9: make good documentation easy

By Andrew Clifford

You can document interfaces easily and effectively if you are not too formal, and if you yourself rely on the documentation you have written.

Interface documentation is critical because it is the contract between one system and another. Without effective documentation, different teams have to take a trial-and-error approach to connecting their systems, which adds significantly to cost and time. How can we provide effective documentation?

There are two common problems with interface documentation: it is difficult to understand, and it is inaccurate.

Interface documentation is difficult to understand when it is made too formal. I know I have made this mistake many times.

One of the ways that we make documentation too formal is to be too clever and break the documentation down into reusable chunks. I have produced documentation with a description of the structure, then a catalogue of data items, and a catalogue of data types, all cross-referenced. Although this may be rigorous and allow sections of interface definition to be reused, it does not help people understand the interface easily.

Another mistake I have made is to store interface definitions in a central repository. This seems like a good idea at the time, but it suffers from two problems. It is hard to keep a central repository up-to-date if the interfaces are being changed by individual teams. The use of a central repository also requires constant management support. When this wanes, the documentation falls into disrepair and disrepute.

I have seen interfaces documented using standard XML definition languages, document type definitions (DTDs) and XML schema definitions (XSDs). Although these are rigorous they do not explain the business meaning of the message. They require some specialist knowledge and are not readily understood by the typical IT developer.

I have been caught out many times by inaccurate interface documentation. As an example, I was recently working on the integration of a financial package into a store system. I received both a DTD and written documentation from the supplier, which were not consistent with each other, and neither of which actually matched what was implemented. There was obviously a lack of connection between the documentation and the development process.

From all these mistakes, I have adopted a more relaxed but effective approach to documentation.

• Keep interface documentation with the documentation of the system that owns the interface. Only centralise interface documentation if other system documentation is centralised.
• Document interfaces by showing sample XML. This makes it easy to understand. Provide concise notes which explain what each element means, whether it is optional, or whether it repeats. XML is self-documenting: avoid redundant documentation such as "the productNumber element contains the product number". Do not get carried away with tables of data items and data types. A few brief notes are all that is required.
• Write interface documentation early in the project and base development and testing on it. Do not have one version for internal use in the project, and another to give to other teams. Follow your own documentation to the letter. When you find mistakes or things that are not clear, fix the documentation.
• When you need to change the interface definition, change the documentation first, and then work from the changed documentation.

Subscription