Improve documentation

Please review and prod me for deficiencies.

Pull requesting just as I'm getting off the train so there may be stupid mistakes.