Docs arrears

[countvajhula]

Summary of Changes

Address some review comments by @benknoble prior to merging the compiler work in #146 . A few other improvements and updates.

Public Domain Dedication

• [x] In contributing, I relinquish any copyright claims on my contribution and freely release it into the public domain in the simple hope that it will provide value.

(Why: The freely released, copyright-free work in this repository represents an investment in a better way of doing things called attribution-based economics. Attribution-based economics is based on the simple idea that we gain more by giving more, not by holding on to things that, truly, we could only create because we, in our turn, received from others. As it turns out, an economic system based on attribution -- where those who give more are more empowered -- is significantly more efficient than capitalism while also being stable and fair (unlike capitalism, on both counts), giving it transformative power to elevate the human condition and address the problems that face us today along with a host of others that have been intractable since the beginning. You can help make this a reality by releasing your work in the same way -- freely into the public domain in the simple hope of providing value. Learn more about attribution-based economics at drym.org, tell your friends, do your part.)

[countvajhula]

This docs PR is ready for review! Tagging Michael as well since the latest bit talks about the 2-level architecture and the use of Syntax Spec (actually, looking at it now, there's a lot in here that would benefit from your review @michaelballantyne ).

[michaelballantyne]

The bit re architecture and syntax-spec looks good to me.

[countvajhula]

I retitled one of the sections "separate effects from other computations" to keep it focused on why you should do this and what benefits it brings, unrelated to order of effects, which is emerging as a different, orthogonal concern. Depending on whether we feel the ideas on "effect locality" are reasonable, I could add some explanation about that in the section on "order of effects" (e.g. "in a threading form, upstream effects are guaranteed to happen before downstream effects").

[benknoble]

I can't recall: are we still hashing out the effects stuff before merging this? If so, would it be worth it to cherry-pick the non-effects related bits and get those merged sooner?

[countvajhula]

@benknoble Sorry for the delay on this, and thanks for staying on top of it! It is indeed still waiting on clarification of the effects stuff but we did resolve that a few weeks ago when I was on vacation. I've been down with flu since my return so I haven't gotten around to writing it out, but I'm aiming to get to it this week and then this should be ready to go. If I can't get to it this week then I'll aim to separate it out and merge the rest as you suggested.

[benknoble]

Understood! I must have missed that you were sick; hope your trip went well and that you recover in peace.

[countvajhula]

OK, I think this is ready! Final review?

[countvajhula]

OK, I've removed everything about effects from this PR and will start a new one for that shortly. This PR should be ready to go!

[benknoble]

Sounds good to me!

[countvajhula]

OK, I will merge 👍 Thank you for reviewing @benknoble and all!