fleshing out the documentation a bit more based on some feedback