W3C home > Mailing lists > Public > www-qa-wg@w3.org > July 2004

Re: [SpecGL Draft] D4 Explain how to avoid using a deprecated feature

From: Lynne Rosenthal <lynne.rosenthal@nist.gov>
Date: Sun, 04 Jul 2004 15:26:49 -0400
Message-Id: <5.1.0.14.2.20040704151331.00b11b90@mailserver.nist.gov>
To: Karl Dubost <karl@w3.org>, www-qa-wg@w3.org

Looks very good.  A few suggestions - attempts at improving the english.

At 05:33 PM 6/29/2004 -0400, Karl Dubost wrote:
>D.4 Deprecation
>
>Previous:
>---------------------------------------------
>Good Practice:
>         Indicate workarounds. Explain and give examples of how to avoid 
> the deprecated feature
>---------------------------------------------
>
>Proposal:
>---------------------------------------------
>Good Practice:
>         Explain how to avoid using a deprecated feature
>
>Meaning:
>         The use of a deprecated feature is discouraged because there is a 
> better technique already available to achieve the same result. It is 
> necessary to explain for each deprecated feature how implementers and 
> users can get rid of it. It might be helpful to give additional 
> information providing insight into the deprecation motivation.

s/it is necessary to explain..../For each deprecated feature, it is 
necessary to explain how implementers and users can avoid using it


>Care:
>         Examples and information about each deprecated features will help 
> the users to smoothly evolve toward the new version of the technology 
> understanding its benefits. It will help to have a faster adoption of the 
> technology.
>         It will help developers to provide tooltip, conversion scenarios 
> helping users to do the transition and it will help them to understand 
> the rationales for implementing the new technology.

s/will help the users to/will help users to
add a comma after technology
Suggest: It will help developers understand the rationale for implementing 
the new technology, to implement an alternative mechanism, and to tool tips 
or conversion scenarios to help users with the transition.


>Related:
>         @@references on benefits of examples when explaining a techno?@@
>
>Technique:
>         1. For each deprecated feature, give one or more examples showing 
> the old way and the new way. If the new way is explained in another 
> document, you might want to give a link to this document, though don't 
> forget that often readers benefit of having everything in one place.
>         2. For each deprecated feature, give an explanation why the 
> Working Group has decided to deprecate the feature. What are the benefits?
>         3. Say if the example you have given is a generic mechanism or a 
> specific example. Users of the technology might adopt the specific 
> example in their implementations and it will limit the use of the feature.

remove 'you have'

>Examples:
>---------------------------------------------
>         Namespaces XML 1.1 deprecation of IRI references includes a link 
> to the deprecation ballot results, providing background information on 
> the proposal to deprecate, what this means with respect to conformance to 
> XML 1.0 and Namespaces as well as the affect on other specifications 
> (i.e., DOM, XPath).
>
>         @@Plenty of examples in HTML 4.01, I will add a few@@
>
>
>
>--
>Karl Dubost - http://www.w3.org/People/karl/
>W3C Conformance Manager
>*** Be Strict To Be Cool ***
>
>
Received on Sunday, 4 July 2004 15:42:11 GMT

This archive was generated by hypermail 2.2.0 + w3c-0.30 : Thursday, 9 June 2005 12:13:16 GMT