D.4 Deprecation
Previous:
---------------------------------------------
Good Practice:
Identify obsolete features
---------------------------------------------
Proposal:
---------------------------------------------
Good Practice:
Identify obsolete features
Meaning:
A feature which has been deprecated in a previous version was at risk.
You might consider to make it obsolete in your present version of the
technology. It is necessary to give a list of obsolete features.
Care:
It gives a clear message to users and developers that obsolete
features are forbidden and not part of the technology anymore. It will
help to avoid the creation of documents mixing old and new techniques
which will be invalid.
It helps to avoid name clashing. When an extension to a technology is
created, developers will use nouns for their extended features name.
Giving the name of obsolete features will help developers to avoid
using the names of previous features which are now obsolete.
Related:
References to the Extension section
Technique:
1. Create a list of all features that are obsolete.
2. Create a dedicated section for it
3. Create a entry in the table of content going to this list
4. For each deprecated feature, create a link to the appropriate
definition in the previous specification.
Examples:
HTML 4.01, Appendix A: Changes lists the elements that are obsolete
and suggests an alternative element for use. "The following elements
are obsolete: LISTING, PLAINTEXT, and XMP. For all of them, authors
should use the PRE element instead."
---------------------------------------------
--
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***