[#1887] Add documentation on deprecation notices

Fixes #1887