Documentation

[canadaduane]

We should update the readme and potentially provide better documentation all around.

Three insights on documentation that might be helpful here, taken from various communities:

1. A (short) synopsis of the architecture can be helpful, even if the details aren't documented. This doesn't have to take a lot of time, and if short, can be changed easily as refactorings take place.

2. Documentation has four quadrants: practical<->theoretical and studying<->working. In the early stages of a project, it can be useful to focus on the "Discussions" (theoretical/studying) quadrant in order to help others understand, but without the burden of writing or maintaining tutorials, references, or how-to guides.

3. "How Docs vs. Why Docs". The key insight here is that "why" is slow to change, whereas "how" is an evolving target.

[toomim]

I agree. Documenting the architecture is high priority. I expect to take a pass on that within 10 days.