Initial documentation revisions

Added scoping information, notes about init & data sharing
limitations and clarifications
Response to CR
Fix some pylint stuff to get the build to pass.
Response to CR
Merge pull request #179 from edx/flowerhack/revised-docs

Flowerhack/revised docs