TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Where to report deprecation? From:"Guy K. Haas" <guy -at- hiskeyboard -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Thu, 04 May 2006 12:56:54 -0700
In a reference manual, or in Javadoc, documenting deprecation is taken
as a matter of course; the deprecation is called out at the point the
class or method is described. Typically, we want to say what OTHER
class or method to use it its place ("lmno is deprecated in favor of qrst").
But what about in developer guides -- the more task-oriented books:
* Do you report deprecations in an appendix and just discuss the new way
to do things in the chapters?
* Do you treat developer guides as always being forward-looking, and
thus leave deprecation reporting to the release notes?
* Do you have any feedback from your readership about what they are
expecting or what their reaction was to your choices?