Docs updates

r? @stevengill @agrieve @brianleroux

(I'm happy to fold these changes together, they're split for reviewability/veto)