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:RE: Where to report deprecation? From:"Nuckols, Kenneth M" <Kenneth -dot- Nuckols -at- mybrighthouse -dot- com> To:"Guy K. Haas" <guy -at- hiskeyboard -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 4 May 2006 16:38:46 -0400
Guy Haas pondered...
>
> 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?
>
First let me say I don't do a lot of coding, but I've done more in the
past and I can speak to what I like to see as a user (which may be
different than what most full-time programmers expect in such
documentation).
The option quoted above is closest to being most useful to me, but IMO
the placement should be reversed. I don't want news about deprecated
items and their in the BACK of the guide, buried in some appendix; I
want them up front--as in maybe the FIRST section of the guide "What's
New in Version X of the Nifty Code Language."
For instance (going back a few years) if you were producing a guide for
HTML 4.0 for those who were familiar with HTML 3.x and I picked up that
guide--the FIRST thing I would want to know is what elements were being
deprecated and what is taking their place (e.g. various formatting
options deprecated in favor of styles). You could then provide me with a
link or page reference (depending on the format of the guide) where to
find more detailed information about the new way of doing things.
In the heart of the guide, I would just describe the new commands, and
perhaps reference in the introduction of the command or element that
this code is replacing the deprecated element "xyz."
To me, it just seems like anything that's going to require the developer
to use a different strategy or different commands than he/she may be
accustomed to using ought to be posted as conspicuously and close to the
front/top of the guide as possible. It would also be nice to have an
explanation of how long before deprecated commands will no longer be
supported in any existing code the developer previously created. This
will at least give developers an idea of how long they have before they
have to completely re-write all the code they've built over the last few
years using previous versions of the development tool you're
documenting.
Again, this is just my $.02; YMMV.
CONFIDENTIALITY NOTICE: This e-mail may contain information that is privileged, confidential or otherwise protected from disclosure. If you are not the intended recipient of this e-mail, please notify the sender immediately by return e-mail, purge it and do not disseminate or copy it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
