- From: Lynne Rosenthal <lynne.rosenthal@nist.gov>
- Date: Sun, 04 Jul 2004 15:26:49 -0400
- 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 UTC