Adjustments to documentation

This PR includes all adjustments to the documentation listed from

https://trello.com/c/lAGH6360/159-improve-data-model-documentation

@jh-bate @jebeck @kentquirk @nicolashery @ianjorgensen 

Please give this a once over, see if there is anything that could be explained better or just differently.  If you can think of an example that you had a question about what would happen, providing that would also be useful (I can fill in what will actually happen).
Ooooh, good question @cheddar. The only thing I can think of as a precedent is the variation in the plural of 'passer-by' as 'passers-by' or (rarely, the analogous case) 'passer-bys' ([n-gram](https://books.google.com/ngrams/graph?content=passers-by%2Cpasser-bys&year_start=1800&year_end=2000&corpus=15&smoothing=3&share=&direct_url=t1%3B%2Cpassers%20-%20by%3B%2Cc0%3B.t1%3B%2Cpasser%20-%20bys%3B%2Cc0)).