RE: Where to report deprecation?

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

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Previous by Author: RE: punctuating the end of bullet points
Next by Author: RE: Where to report deprecation?
Previous by Thread: Re: Where to report deprecation?
Next by Thread: RE: Where to report deprecation?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads