update deprecation docs

stumbled over a wrong description and looked if there were others I could improve