Clean existing documentation

• at least remove dead doc.
• at least 1 complete pass on the whole doc.

---

Migrated from T2235 (view on Phabricator)