Update some documentation

Also add some additional undocumented but generally understood points, for clarity reasons. First revision made in GitHub's Atom text editor (not really relevant, but wanted to document that as well)