one talks about children, the other about references. tried to make it
more understandable.

objects vs documents is a huge mess indeed. its a mess for the orm as
well, i just replaced "document" with "entity" but left "object". will
clean this up here.