I like the idea of "Contract-driven development", which should in principle help with this kind of thing. Services expose an API schema (say, OpenAPI), and othe

I like the idea of "Contract-driven development", which should in principle help with this kind of thing. Services expose an API schema (say, OpenAPI), and other services can register usages of that contract. This framework is usually intended to capture low-level collaboration between teams; if you need to make breaking changes to an API, you can see who's depending on it. But you can also in principle build a graph of interactions based on who is consuming contracts. Another direction you can take this is to analyze traces from your production system, to determine who _actually_ calls who, instead of who claims to call who. I've not seen tools that offer this, though I know many of the big guys are doing this kind of analysis. As far as the article goes -- I think all docs should be written in Markdown and checked in along-side the service/code that's being documented. I've done diagrams in MermaidJS, but you can use fancier code tools and a Make script if you prefer. You can use something like Gitlab Pages to render your docs really easily. It's hard work maintaining the discipline to keep docs up to date, but at least keeping the docs next to your code you make it _possible_ to have a chain of PRs updating the documents at the same time, and a given release tag showing the docs changes associated with that release's code changes.