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).
I think you are saying here that any event can have an 'annotations' field -- and if there is one, it must be an object and have a code member. I think you should say so explicitly (perhaps steal the line above). 

But also, I wonder whether we'd be better off making annotations their own event type with a reference to another event -- essentially, a special type of note (as that's what the notes field has). Advantage would be that annotations could be richer and could be extracted or ignored as necessary; disadvantage is an extra record type to deal with if you are looking at a particular data type and want to know if it has annotations.