Documentation fixes / review

Mostly stylistic changes to the documentation, with a few 'todo' notes mixed in.

Wait to merge this.