doc : rebase

closes #2733

My writing probably needs a lot of editing.
So am I: pull merges automatically, which is rarely what you want.