The development of integrations and APIs is complex and demanding – and there is a focus on getting the actual job done. Still, one should also ensure top-notch documentation.
The agile manifesto prefers a running system over extensive documentation, but having integrations documented is unavoidable. On the other hand, documentation is part of the definition of done in agile development. And yet documentation is often created on a best effort basis, which translates to minimal effort.
The documentation of integrations comes with similar challenges such as dependencies and complexity thus producing it is not straightforward either.
So, why should we invest time and money in the creation and maintenance of documentation?
There are many reasons. Up to date information will decrease the time and also cost needed for knowledge transfer, development, testing and incident resolution. In the long term, it will also help to avoid vendor locks by increasing overall visibility.
As highlighted in the Public Administration API Principles, integration and API documentation increases cooperation, reusability, interoperability, information security, data protection and quality. It is useful for both technical roles such as development, testing, support and IT security and business-oriented roles, such as operation, product owner and analyst.
The main challenge to do documentation is the nature of integrations – they are the glue in the middle – the part which connects different systems. And ultimately the "grey area" where things get unclear.
In my experience, the following points need to be considered when planning and implementing integrations and their documentation.
Manifesto for Agile Software Development
Ministry of Finance, Finland: Public Administration API Principles
Do you see the documentation of integrations and APIs as a challenge? We would like to hear about your experiences so do not hesitate to reach out! And stay tuned for more articles where me and my colleagues will delve into topics such as iPaaS platforms, API monetization, and overcoming the typical integration challenges that I mentioned in the start of this post.
Klaus has 30+ years of Information Technology experience in various fields of business including retail, transportation, pension insurance and finance. He has extensive knowledge of data technologies ranging from reporting and ETL (Extract, Transform, and Load) to integrations. Currently Klaus is focusing on API management, application integration, event streaming and test data management.