W3C home > Mailing lists > Public > public-webplatform@w3.org > July 2014

Re: QA Sprint, what to do with deprecated specs

From: Amelia Bellamy-Royds <amelia.bellamy.royds@gmail.com>
Date: Sat, 5 Jul 2014 11:13:51 -0600
Message-ID: <CAFDDJ7yrw02Efnu_iQbTLRWmDZA9UT=k2QoYivQTZu6QV4cUOQ@mail.gmail.com>
To: Renoir Boulanger <renoir@w3.org>
Cc: List WebPlatform public <public-webplatform@w3.org>
As I understand it, a "Working Group Note" is essentially an abandonned
"Working Draft" which will not be pursued further.

For marking the standardization status in the reference pages, we could
either

(a) update the list of options for the W3C status [1] to include a "Working
Group Note" option, and update the templates and style sheet to apply an
appropriate icon (probably the same as is used for deprecated); or,

(b) just use the "deprecated" label.  The current definition on the
property page [1] is wide enough to include abandonned proposals, but it
might cause confusion because it isn't what people think of as a deprecated
spec.  (On the other hand, those not familiar with W3 processes might not
realize that "Working Group Note" is only used for abandonned proposals, so
deprecated might be more clear.)

However,* this brings up a larger issue to be added to the list of TODOs*
(content issues where a decision needs to be made about the desired course
of action) [2]:

What is the WebPlatform Docs policy regarding deprecated or obsolete
features?  Do we still want to maintain those reference pages for
completeness sake?

Some reviewers have been marking for deletion all pages on
deprecated/obsolete properties.  However, that seems to me to be contrary
to the idea of building up a lasting, comprehensive reference guide to both
established and experimental web technologies.  The nature of experimental
technologies is that some will be abandoned or deprecated.  A good
reference page should clearly indicate that something is deprecated, but
shouldn't erase the past.

However, not deleting deprecated pages, especially for things that were
never widely implemented, could create problems by cluttering up automatic
listings pages with irrelevant pages if additional checks aren't added to
screen them out.

The closest policy statement I could find is from the "Pillars" page [3],
which says:

   - The stability and implementation status of features will be clearly
   marked; however, there is no requirement that features be stable or widely
   deployed to be included.

What do people think?  What should be the approach to deprecated features
or abandonned drafts (i.e. Working Group Notes)?  How should we indicate
this policy to contributors?  Does anything need to be changed about the
way deprecated features are identified in the documentation?

On the readiness marker issue, my perspective is that article readiness is
separate from the feature status. Once the reference page has been updated
to clearly identify the deprecated/obsolete status of the feature, the
article itself can be marked "ready to use".  Does anyone have any concerns
about that?

Amelia

[1]: http://docs.webplatform.org/wiki/Property:Standardization_Status
[2]: (email from me to the list, July 4, titled "List of TODOs discovered
during the QA Review"  -- couldn't find the archive link, since w3.org
websites are down!)
[3]: http://docs.webplatform.org/wiki/WPD:Policy/Pillars


On 5 July 2014 09:43, Renoir Boulanger <renoir@w3.org> wrote:

> Hi all,
>
> I stumbled on an interesting case; An section which is now a Group note
> and a related new working draft that is completely different.
>
> If you look at filesystem API [0] page, it links to a, now group note
> [1]. But I found a related spec [2], but i don’t find the matching section.
>
> What do we do in this case?
>
> - Keep reference to group note
> - Update docs status to group note ***
> - Set readiness as: Out of date
>
> *** The document [1] says its a Group Note, but we do not have this
> choice, is it deprecated?
>
> Opinion?
>
>   [0]: http://docs.webplatform.org/wiki/apis/filesystem/Entry/isDirectory
>   [1]: http://www.w3.org/TR/file-system-api/
>   [2]: http://www.w3.org/TR/FileAPI/#dfn-file
>
> --
> Regards,
>
> Renoir Boulanger  |  Developer operations engineer
> W3C  |  Web Platform Project
>
> http://w3.org/people/#renoirbhttps://renoirboulanger.com/  ✪
>  @renoirb
> ~
>
>
>
Received on Saturday, 5 July 2014 17:14:20 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:21:02 UTC