RFC: Documenting Cabal interactions through diagrams

## Motivation

Cabal (and cabal-install) could be better documented for the sake of its own contributors; the specification we have does not directly translate to the code, which is understandable, however as such, we would benefit of having a documentation that depicts how Cabal's (and cabal-install's) inner workings function code-wise; we somewhat have that, but nothing that shows us how the modules are interacting with one another. There's often guessing and doubt when changes need to be made and the original writer of the code is not around any more, or even when the original writer of the code is around, but it's been so long ago that it doesn't make a difference.

Ideally, the contributors shouldn't need to rely on each other to answer questions that could easily be answered by a proper code documentation. Yes, apart from asking other people, the contributor could simply take a peek at the code and decipher it, but the codebase is not always trivial; why potentially slow development down to a crawl when a quick look at a documentation could make everything painlessly smooth?

## Means

Now, how the heck one documents a project as big as Cabal (and cabal-install)? The most straightforward and friendly way (keyword being friendly) would be using diagrams. People can just look at them and get the grasp of what's happening, hopefully. A diagram based approach brings several benefits:

* Easy to understand, it's a diagram after all, as long as the notation used is not overcomplicated, we'll be fine in this aspect;
* It will provide a bridge, and a very clear one at that, between the discrepancies regarding the specification and the codebase;
* After the whole thing is out, the maintenance effort would possibly be comparable to the docs we have today, if not less;
* Considering the practicality of diagrammatisation, onboarding of fresh new collaborators will be a cake walk;
* and likely other things that didn't came to me right now.

## Ends

Of course, I'm well aware that the gains of such endeavour won't come for free, at first it will demand a bit of effort, imaginably from multiple people, and also afterwards, to maintain it up to date (although much less); nonetheless I do believe that it will be a worthy investment that greatly outweigh its costs, and that in the long run we'll reap its benefits.

Taking into account the words above, I'd like to use this issue as a place of discussion for the topic, maybe even reach a consensus and bear something useful from it.