doc : rebase

closes #2733

My writing probably needs a lot of editing.
We should probably mention that tests need to be ran before force pushing to a repository.