Doc update

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| Refs tickets  | #1002, #1261, #1552, #1765, #1763
| License       | MIT
| Doc PR        | -

Doc re-organization highlighting emphasis on maintaining BC but clearly outlining areas where it is broken.

/cc @cmfcmf
The stars ** are messed up here. It starts in line 575 and should end in line 576 after "note:". There shouldn't be stars. In 577.