Documentation
canadaduane opened this issue · comments
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:
-
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.
-
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.
-
"How Docs vs. Why Docs". The key insight here is that "why" is slow to change, whereas "how" is an evolving target.
I agree. Documenting the architecture is high priority. I expect to take a pass on that within 10 days.