Pete's docs

Supersedes #822

Cherry picked the commits we need from #822