Updates docs again.

Elaborates more on #1937
@jmeas Sorry for the extra work you had to do :sunglasses: