I wouldn't have bothered reviewing the docs in this PR, since they haven't been modified significantly from what's already in the modeling module.  Mainly because this is still a proposed API change--if we go with it then I'll go through the docs very carefully.