Updates docs again.

Elaborates more on #1937
i am not a fan of this since it is a :hourglass: :bomb: as far as going out of date

we should just keep the "minimal" on purpose docs like @jmeas said :)