Major Docs Patch

Am baby sitting my aunt.. so using time to make revel docs better..

here's first patch, but going thru and tweaking bits and pieces..

I kind want to push to the "upstream"  origin and have perms, but am nervous to do so.. (maybe into a new "docs_next" branch)


Perhaps more specifically "the developer may" instead of "user"?