Fwd: Optional Extra Links for Specs

Here's a note on what the DOM3 events spec is doing with links at the 
top of their document.

Anyone here have any opinions as to whether we should follow their example?

-Eric.

-------- Original Message --------
Subject:  Optional Extra Links for Specs
Resent-Date:  Tue, 07 Dec 2010 17:12:56 +0000
Resent-From:  chairs@w3.org
Date:  Tue, 07 Dec 2010 12:12:47 -0500
From:  Doug Schepers <schepers@w3.org>
To:  chairs@w3.org <chairs@w3.org>



Hi, Chairs-

PubRules (W3C publication rules) requires certain links to be present at
the top of a Technical Report (TR) document.  These include:
* This Version
* Latest Version
* Previous Version (where applicable)

Because it can be weeks or even months between public updates to the TR
drafts, some groups have been adding an additional link to the Editor's
Draft (which, in contrast to early member-only policy, are now publicly
visible, since most groups now work in the public).  This allows people
to consult the latest draft, so they don't review or implement
out-of-date materials.

Also, in response to complaints that it is hard to find the link to the
mailing list for sending comments on the spec, I have added an
additional link, Public Comments, to indicate the mailing list.  This is
normally buried in the "Status of This Document" boilerplate, which
apparently some people merely skim or skip, and adding a link on top
provides a clear and consistent place for readers to find that information.

There is real value in consistency between specifications, in both what
is said, and where the information is located.  Consistent specs are
easier to review properly, less at risk for misunderstanding subtle
differences between groups, and allows readers to apply patterns they
have learned from one W3C spec to others (following the "don't make me
think" principle).  Nevertheless, these additional links are intended to
be optional, for use by groups that see value in them; if they are used,
however, it would be best for them to be used consistent with other specs.

You can see an example of the "extended dance remix" of the front matter
in the DOM3 Events spec [1], which has the following links:
* This version
* Latest stable version
* Previous version
* Editor's Draft
* Public Comments

We would like to have feedback on this practice, and if it is generally
agreed to be a useful addition, would like to see it adopted by other
groups.  What do you all think?


In addition to this, there is also an ongoing thread in the HTML WG on a
pop-up warning that informs readers of the latest editor's draft, so
they don't invest time in reviewing a draft which may have fixed some of
the issues they would encounter in the TR version [2]. This is a
separate issue, but related.  Again, if this is going to be used, it
would be good for it to be consistent between groups.  Thoughts on this
are welcome, too.


As yet, neither the additional links nor pop-up warning are explicitly
addressed by pubrules, but some policy
may be enacted at some point, so it would be good to see if we have
consensus here.


[1] http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html
[2] http://www.w3.org/Bugs/Public/show_bug.cgi?id=11324

Regards-
-Doug Schepers
W3C Team Contact, SVG, WebApps, and Web Events WGs

Received on Tuesday, 7 December 2010 18:25:14 UTC