MRG: massive rewrite of docs

I added greatly to the docs, and did some rewriting.

If any of y'all have time, I would be very grateful if you can scan any pages
that seem interesting to y'all.

I plan to merge this soon (maybe tomorrow) on the basis that we allow
documentation only PRs without review, but I would love any comments if y'all
have time.

After that we can release, maybe tomorrow or Wednesday.