grammar
avoid repetition; the heading already mentions that this stuff is deprecated
use a more suitable Sphinx directive
use simpler language

This likely fixes the grammar, but am not sure.
Merge pull request #854 from tshepang/diff

some doc improvements