Re: Upcoming changes for W3C reports and our /TR pages

Hi,

We have reached the first milestone of the different changes announced
two months ago by Philippe.
Here's a summary of what has been done:
1/ pubrules now requires a "rel=canonical" <link> in all the
specifications. If you are using bikeshed or respec, these tools are
already taking care of this for you.
The documents published *before* Oct 1st, 2017 offer that link via a
HTTP header.

2/ outdated documents should now display a warning (eg. [1]) pointing
the readers to the latest version of the specification (thank you Marcos
and Dom for reviewing the script).
If for whatever reason, you believe a warning should appear on a
specific version, you can request an exception by editing [2] and
submitting your pull request.

If you notice any problem with the changes above, feed free to contact
me on IRC or email.

For the next milestone, scheduled to be achieved by the end of this
month, we will implement the latest version link proposal for the
leveled specifications. Again, if there's any concern, please get
in touch with me.


Denis

[1] https://www.w3.org/TR/2017/WD-appmanifest-20170920/
[2] https://github.com/w3c/tr-design/blob/gh-pages/outdated-exceptions.txt


On 08/04/2017 10:29 PM, Philippe Le Hégaret wrote:
> Dear Editors,
> 
> with the increasing development of specifications, finding a technical
> report is now a difficult process. Readers get lost in the pages under
> https://www.w.3.org/TR/ and may be reading old documents without
> realizing it.
> 
> Our overall goal is that /TR should represent what should be implemented
> for the Web.
> 
> We are looking at improving our listing of technical reports
> (https://www.w3.org/TR/, also known as /TR) and technical reports
> management by focusing on the latest documents and marking old versions
> as obsolete/outdated/retired. Obsolete is used for Obsoleted
> Recommendations, introduced by the 2017 Process. Outdated will be used
> for dated documents that have a newer dated version (see item 3 below).
> Retired is currently used by Notes abandoned by Interest or Working Groups.
> 
> We're focusing on two general use cases in this overall:
> - the community at large, who favors documents that are considered
> completed or mostly completed by the Group;
> - the implementers community, who favors documents containing the most
> recent discussions of the Group.
> 
> As outlined in item 4 below, the future /TR listing page will allow
> individuals to filter their views based on their interest or focus.
> 
> If there is interest, we'd happy to organize a call in September
> explaining the upcoming changes.
> 
> More details below.
> 
> ----------
> 
> Following useful feedback received from spec-prod and the AB, here's an
> update of the set of changes that we intend to do in the next 3 months
> (also listed on github [1]).
> 
> 1/ To ensure that readers get pointed towards what the Group believes to
> be most relevant, we're introducing a convention for Latest Versions
> links for leveled specifications [2][3].
> 
> For specifications with multiple levels such as CSP (CSP-1, CSP-2,
> CSP-3) or used in the CSS Working Group, we are going to harmonize new
> links to help identify the most advanced document on REC track, the
> documents with the latest features, the editor's draft and the list of
> the different versions:
> 
> - /TR/shortname/ed/: editor's draft (outside the /TR space) associated
> with the document returned by /TR/shortname/
> - /TR/shortname-n/ still points to the latest published version of the
> level n
> - /TR/shortname/all: cover page with list of the different versions
> - /TR/shortname/upcoming/:
>    * the latest version of the highest level not
> obsoleted/rescinded/retired
>    * the obsoleted/rescinded/retired document
> - /TR/shortname/latest/: points to the first document in the following
> list:
>    * the highest level being a CR, a PR, or a REC that is not obsoleted
> or rescinded
>    * the highest level being a Note if not retired
>    * the lowest level being a WD
>    * the obsoleted REC or the rescinded REC
>    * the retired Note
> - /TR/shortname/: the WG decides whether it should point to the upcoming
> or latest versions. This is already the case today so this should be
> invisible.
> 
> Note, the terms 'upcoming' and 'latest' in the new links are the result
> of several discussions but we still welcome alternative proposals for
> what those terms can be until October 1.
> 
> For an example, see
> 
> https://github.com/w3c/tr-pages/wiki/Latest-versions-proposal-for-leveled-specifications#example-with-the-csp-specifications
> 
> 
> We are planning to deploy that latest version links proposal starting
> from 1 November 2017.
> 
> 
> 
> 2/ To point search engines to the most relevant document, we're going to
> use rel=canonical in specs [4][5]
> 
> We are going to make that link as a requirement in the technical reports
> starting from 1 October 2017. Dom already pushed that change to respec
> and bikeshed so by default, if you are using one of these tools, there's
> nothing to do. For the specs published before that date, we will add
> that link via a HTTP header.
> 
> 
> 
> 3/ To encourage readers not to look at outdated documents, we will add a
> required
> JS for deprecation [6][7]
> 
> One big issue we currently have with /TR is to know whether the document
> being read is obsolete or not. For historical reasons, we need to keep
> old versions of the specifications around but it's important to mark the
> outdated documents as such or at least make them easily recognizable.
> Since it would be too tedious to edit a document after a new dated
> version is published, we are thinking about adding a script that will
> take care of this if the document is to be marked as outdated.
> Here are some mockups:
>      https://w3c.github.io/tr-pages/outdatedspecsmockup/html4/
>      https://w3c.github.io/tr-pages/outdatedspecsmockup/html-aria/
> 
> Some exceptions will be allowed so for specific use cases, the
> deprecation note can be skipped.
> 
> You can find the deprecation workflow at
>    https://w3c.github.io/tr-pages/deprecation.svg
> 
> We are planning to make that JS link a requirement in the specs starting
> from 1 October 2017.
> 
> 
> 
> 4/ To ensure that /TR represent what should be implemented for the Web,
> we are looking at redesigning it [8].
> 
> The last item is related to the design of the /TR page. As mentioned
> earlier, that page is unusable and doesn't help the users to find
> the documents they are looking for. /TR should list what the web should
> look like in the future so the focus should be put on the
> latest/upcoming versions of each specification.
> Of course, we'll provide a view of the other versions but that won't be
> the default one.
> We also want to add different types of filters to help narrow a search
> to satisfy the various audiences.
> Although the design will definitely change, a mockup is available
> to get a rough idea of the filters we are thinking of:
>      https://w3c.github.io/tr-pages/mockup1/
> 
> Also the list of tags will be revised and will be managed by the
> community.
> 
> Denis & PLH
> 
> [1] https://github.com/w3c/tr-pages/wiki
> [2] https://lists.w3.org/Archives/Public/spec-prod/2016OctDec/0052.html
> [3]https://github.com/w3c/tr-pages/wiki/Latest-versions-proposal-for-leveled-specifications
> 
> [4] https://lists.w3.org/Archives/Public/spec-prod/2017JanMar/0008.html
> [5] https://github.com/w3c/tr-pages/wiki/%27rel%3Dcanonical%27-in-specs
> [6] https://github.com/w3c/tr-design/issues/114
> [7]https://github.com/w3c/tr-pages/wiki/Latest-edition-proposal%3A-required-JS-for-deprecation
> 
> [8] https://github.com/w3c/tr-pages/wiki/TR-redesign
>

Received on Tuesday, 3 October 2017 13:44:43 UTC