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.