better organize docs so that examples are used consistently

[drmason13]

The current docs are fine, but you can tell that it's not all written at the same time. There's inconsistency in the style and organisation.
I'm working on some basic principles, rules to follow so stuff ends up being documented in predictable places, and things don't get forgotten about in weird corners.