Document overall view of the codebase

[tuturto]

Docs are problemating, as they often fall behind when code evolves. Still it would be good idea to have a section in docs to give overall view of the codebase and point out major points of interests (main code, tests, docs, maybe most relevant parts of the code too). This helps new contributors to get started and refreshes memory of the old ones.

[Kodiologist]

I think it's a mistake to document aspects of the implementation that aren't supposed to be user-visible. We'll have our hands full maintaining documentation for user-visible parts of the language. @allison-casey Do you agree with closing this?

[allison-casey]

I think it's a mistake to not document the rational and design philosophy of the codebase. It can be invaluable to future maintainers. It's understandable though to not worry about it till 1.0. I'll happily do it once we got that milestone

[Kodiologist]

With Allie missing in action, this is very unlikely to happen.

Anyway, let's be honest with ourselves: the implementation has no design philosophy. It's developed organically over many years, which is a polite way of saying that it's kind of a mess. Somebody who really wants to document it should put in some serious elbow grease to make it worth documenting first. Even then, I wouldn't be eager to maintain internals documentation.