> Yury: do you want to do the re-organization into high- and low-level APIs?  If you'd like me to do it, I'll need a more explicit listing of which APIs fall into which category.

Sure, I'll update this issue tomorrow or the day after with a more detailed plan.  Or maybe I'll start working on the 1st PR and will just give you push privileges to my repo.  Would be cool if we can push the first rewrite live as soon as possible.

> Also, do we want to create an explicit high-level and low-level sections and push everything else down a level, or just leave it implicit in the ordering?

Yes, I'd go for 2 explicitly separate sections.  I think it's important to focus average readers' attention at the high-level bits and pieces, leaving low-level APIs and details to framework/library authors.

And, again, thanks for help.

Adding Carol to the nosy list as she seems to be interested in this topic too.