Required updates to "in-repo-docs" vs RTD docs

[andrewphilipsmith]

Beyond the scope of PR #159, the following changes to the docs are still required:

• Resolving overlapping content between Contributing.md and README.md
• README.md and docs/index.md contain repeated content - look at mkdocs config to link these.
• Add diagrams Add diagrams to docs #121 (comment)

Originally posted by @sgreenbury in #159 (comment)