Update modeling docs a bit

Here's what I found when updating the docs.
@embray You mentioned you are going through the docs yourself, so probably we can throw away this one.

I have to go ... I'll look in detail at your modeling changes tomorrow ... hopefully they will be in master then. :-)