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

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.

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.

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.

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 ***