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.
