Current documentation of internal services in ACE container architecture

Containerized ACE installations are, of course, composed of microservices. The dependencies between these microservices are not obvious to the customer's eye. This results in confusion about the impact of changes. IBM makes efforts to have all the dependencies resolved automatically; but that cleverness backfires when there is a gap, because the internal infrastructure is so opaque.

Documenting the purpose of the internal features would help orient the customer, assist them in understanding that, if my problem is -here-, it's possible that microservice -thus- is implicated.

Here is the specific experience I had that led to this idea:

We had a problem whose resolution eventually reqired the shipping of a patch.

Applying the patch caused a restart of some of the services, but not of all of them. This seemed reasonable; only the things that needed to be cycled, should be. Microservices FTW.

But the map of what needed to be recycled was incomplete, and the behavior change that was the intent of the patch did not happen. In the event, it was the presence of an option in the catalog of connectors I could configure.

Here's the key: I had no sense of where that list of options came from, no basis for understanding which parts of the system might, in malfunction, have contributed to the list. I was flying blind, all I could do was turn back to support and say "It no work!".

If I knew that the 'cas' was the 'connector auth service', there would have been a snowball's chance in warm places that I could have determined that a problem with the list of connections might be related to it.

I recognize that maintaining documentation for a fast-moving product is a challenge. But I claim it is -more- important that you be transparent in that case, not less. If you in fact have rapidly evolving internal architecture, you are necessarily invalidating whatever cargo-cult knowledge your customers have accumulated about system behavior. If you invalidate that experience and fail to tell them, it's a problem.

The microservice architecture of your app is open to inspection by your users. You can't hide it from them, so avoiding documentation because it might change doesn't really win you anything. Seems to me you just need lots of versions of the docs, which your site seems to be getting better and better at doing.