Updates docs again.

Elaborates more on #1937
Yeah I'm cool with that.