Recently, I've became the integration lead for a large distributed system. I have two main challenges before I can take on anything else: first document all system interfaces and it's relationships and prepare to upgrade for a new cloud infrastructure (and getting away from IBM stuff).

The first goal is tricky. We got an excel spreadsheet with all applications, databases, clusters and file systems. Every change on our system must be reflected on this spreadsheet, for example, a new web app being deployed. How it communicates?

This solutions is not good, it's hard to keep update, hard to consume and our team does not trust it.

My question is: How to document system interface (interfaces being boundaries where systems communicates)? Have you guys faced similar challenge? The previous integration lead tried to create a custom app for that, but is just too much effort. I was considering using confluence (wiki) to accomplish the same.


closed as too broad by gnat, Thomas Owens Apr 16 at 12:08

Please edit the question to limit it to a specific problem with enough detail to identify an adequate answer. Avoid asking multiple distinct questions at once. See the How to Ask page for help clarifying this question. If this question can be reworded to fit the rules in the help center, please edit the question.

  • The question has been downvoted, so what should I improve? – Bruno Moreira Apr 16 at 11:50
  • Still on hold even after I clarify the question, it is still too broad? – Bruno Moreira Apr 16 at 14:23
  • 1
    Yes, it's too broad. Your question amounts to "How do I document a distributed application?" Entire books could be written about that subject. "How to document system interface (interfaces being boundaries where systems communicates)" does constrain the scope some, but documenting system interface boundaries still amounts to documenting the entire system, in my view. – Robert Harvey Apr 16 at 14:43
  • Agreed that asking "How do I document a distributed application" is too broad. However, narrowing it down to only system interface still too broad? Then the question should not be asked I and should read a book, which is a good advice, but the purpose here is to discuss, right? Anyway, I got the anwer, seems to me that the question was clear enough to some. – Bruno Moreira Apr 16 at 14:49
  • 1
    This isn't a discussion forum. We prefer clear questions that are succinctly answerable. – Robert Harvey Apr 16 at 14:52

Documenting a complex system requires to document the parts and their relations.

Of course, ideally you could dream of a great modelling tool that would show every aspect of the architecture in a graphical way and allow you to navigate across the structure and behaviors. The reality however is that it is extremely time-consuming to gather and disambiguate all the technical info, and to draw the elements in a way that remains accurate and readable. I’d say, based on my own experience, that it’s almost impossible to do this once a very complex system is build (unless your team is composed of UML experts who prefer to communicate graphically than to write code).

Another approach is to use a configuration management database . These are ideally suited to document assets (components, applications, database) and their relationship. However these are often designed with primarily hardware and software assets, and less with dynamic aspects like deployment of instances, or data structures that can create a hidden relationship.

Finally, the most pragmatic way could be just a wiki like you yourself found out (some years ago I would have proposed HTML directly, since after all Tim Berners-Lee invented it for the purpose of documenting the very complex networked structure of the CERN information systems).

The big advantage is that everybody can write text according to a template. Just keep the template simple, in order to avoid contributors to have to document things that are already documented somewhere else.

The other big advantage is that you can easily navigate the relationships according to different needs:

  • you could start with a functional view, navigate to the involved components, navigate then either to the underlying technologies, or deployment nodes, etc...
  • tou could start with an interface, navigate to either the protocol, or the underlying data-structures that are exchanged, and from there to the domain entity, and from there to the applications using that concept
  • (invent your own scenario here)

If you think well about the templates to be used (e.g. application, component, library, data structures, messages, processing nodes, interfaces, etc....), you can really built a very useful minimalistic documentation in which every click would correspond to a potential impact.

The challenge is that you have to connect this documentation to the reality to keep it up-to-date. This means that updating the documentation (or creating the missing entries) should belong to the definition of done. And you need to think about how to keep it in sync with releases.

The main drawback is that it requires some discipline, and maintaining a lot of lists (with hyperlink to the related items).

The good news is that the Confluence wiki can be integrated with Jira, linking from or to change requests, or automating the production of some lists that can be embedded in wiki pages.

The other good news is that wiki systems allow to watch changes on a certain page, so it could also improve awareness of people regarding potential impacts on the parts they are interested in, so that not everything relies on your own shoulders.

  • Thanks @Christophe, so rewarding to receive such comprehensive answer! Confluence seems to suit well this scenario, and it is as you said: keeping it up to date is the key challenge. Starting a new position we have to deal with what is my responsibilities, what should I be accounted for, how to measure my performance, etc. In this case, keeping such documentation is key for me. – Bruno Moreira Apr 16 at 12:36

Not the answer you're looking for? Browse other questions tagged or ask your own question.