Docs review

I found GitHub worked real well to review changes to docs, but not to review the full document, so I'm trying out this new system where I put comments in the docs themselves.

We should open GH issues for those (one per file, probably) so we can track them.

The idea's to take a file and go through each todo, do it, and then remove it.

Thoughts on the process?