W3C home > Mailing lists > Public > spec-prod@w3.org > July to September 2017

Upcoming changes for W3C reports and our /TR pages

From: Philippe Le Hégaret <plh@w3.org>
Date: Fri, 4 Aug 2017 14:29:49 -0400
To: spec-prod <spec-prod@w3.org>
Cc: Denis Ah-Kang <denis@w3.org>
Message-ID: <ab72b7cc-0445-f7a8-9af5-01a3446602bc@w3.org>
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 Friday, 4 August 2017 18:30:00 UTC

This archive was generated by hypermail 2.3.1 : Friday, 4 August 2017 18:30:00 UTC