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).
My mental model for annotations versus notes actually has a semantic difference between the two.  I'm not against moving annotations to a notes-like object, but let me explain why I've been more in favor of keeping them as a field.

Specifically, I see annotations as information pertaining to the datum that *must* always accompany the datum.  They are extra fields that tell you about what interpretations you can safely make about the data point in question.  "mismatch-stream" indicates that there was a disconnect in the stream of basal events, for example.  That is necessary information when looking at the event, because it helps identify that something funny might've been going on.

I think that moving annotations off into their own stream would separate this knowledge away from the event.  Basically, it would allow for someone to load up the event without seeing the annotation (because they didn't ask for the annotations) and thus not know that there are caveats to the datum in question.

Notes feels to me like it doesn't have that same problem.  Even if you have a thread of comments that explain a datum, the datum itself is still accurate and correct whether you are aware of those comments or not.