edits to the docs based on the work currently done
tidy up code snippets and dat 78 char word wrap
Merge pull request #122 from github/update-specs

edits to the docs based on the work currently done