Round 2 of docs, incorporated most comments by Boyd.