Re: [SpecGL Draft] D4 Identify each deprecated feature.

Hi Karl

Nice rewrite, thanks.  Comments below.....


>D.4 Deprecation
>
>Previous:
>---------------------------------------------
>Principle:
>         Identify each deprecated feature. If there are deprecated 
> features from a previous specification version, let the reader know about them.
>---------------------------------------------
>
>Proposal:
>---------------------------------------------
>Principle:
>         Identify each deprecated feature.
>
>@@Need to define deprecated feature@@ (See the mail about 
>deprecation/obsolete in www-qa)

See previous email.

>Meaning:
>         When a new version of a technology is created, needs evolve. It 
> will be necessary to keep a detailed list of the deprecated features of 
> the previous version of the specification.

The wording is awkward. Suggest
When a new version of a technology evolves, it is important to provide a 
list of the features being deprecated from the previous version of the 
specification.  This list serves to notify developers and users of the 
technology.

>Care:
>         When the technology is implemented, it helps the developer to 
> know which features will be superseded in the next version of the 
> technology. It will also be easier to implement conversion mechanisms 
> when necessary.

Awkward.  Suggest
It helps developers know which features will be superseded in the next 
version of the technology.  Moreover, it provides them time to remove it 
from their code and if appropriate implement an alternative method.

>         It will help the user of the technology to know what are the 
> features at risk when they create document and encourage them to use new 
> appropriate methods.

Suggest:
It helps users of the technology know which features to avoid using when 
they create documents.


>Related:
>         @@Look for references on deprecation@@

Other GPs in this section.

>
>
>Technique:
>         1. Create a list of all features that are not encouraged anymore.
>         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 specification
>
>Examples:
>         "HTML 4.01" [0]
>                 The specification has a full list of "elements" [1] and 
> "attributes" [2]. The deprecation status is given in the two lists.
>                 There is an entry in the table of content to these two lists.
>                 Each element/attribute is linked to its definition in the 
> specification
>
>         [0]http://www.w3.org/TR/1999/REC-html401-19991224/
>         [1]http://www.w3.org/TR/1999/REC-html401-19991224/index/elements.html
> 
>[2]http://www.w3.org/TR/1999/REC-html401-19991224/index/attributes.html
>
>         IRI Avoid doing. Section 2.2 .2 Use of IRIs as Namespace Names in 
> Namespaces XML 1.1 discusses the deprecation of relative IRI references. 
> Difficult to find, luckily this is a very short Rec.

Excellent.  Its good to provide examples of what not to do.

-regards
Lynne

Received on Saturday, 3 July 2004 19:31:18 UTC