Updates docs again.

Elaborates more on #1937