Document what to do about the deprecated annotations


Since it took us a while to figure out what to do about the long-standing deprecated notice on the annotations, I think this will be useful to others.