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