W3C home > Mailing lists > Public > spec-prod@w3.org > April to June 2012

Re: Thoughts about future pubrules

From: Sandro Hawke <sandro@w3.org>
Date: Tue, 08 May 2012 12:09:15 -0400
To: Alexandre Bertails <bertails@w3.org>
Cc: ted@w3.org, Philippe Le Hegaret <plh@w3.org>, spec-prod <spec-prod@w3.org>
Message-ID: <1336493355.24034.107.camel@waldron>
On Wed, 2012-05-02 at 13:40 -0400, Alexandre Bertails wrote:
> [snip]
> >>
> >> Comments?
> >>
> >> Philippe
> >
> > ReSpec is a red herring here.  It's not part of the problem or part of
> > the solution to the webmaster bottleneck.  It does help reduce the pain
> > of complying with pubrules, but it does that already, without any
> > changes to the current system.
> >
> > What we need is a web form (aka web service) like this:
> 
> A Web form won't save you from mistakes.  We'll still need to compare
> the data provided in the form with the data extracted from the spec,
> to check if they are aligned.
> 
> With ReSpec, you already have metadata in the document.  The tool
> would just show you the extracted data and ask for your final
> approval.
> 
> To summarize, all the informations at the top of the spec should be
> generated from this data.  This would prevent errors.
> 
> >     Shortname:
> >     Publication date: (today, or any date in the future)
> >     Publication time: (maybe you want it to appear at 2pm or something)
> >     URLs to fetch:
> >         (each of these is fetched and put into the new dir;
> >         the part after the last slash remains the same; one of
> >         them must be Overview.html)
> >
> >         (it would be nice let people just name a CVS or HG directory, too.)
> >
> >     Spec Groups:   (like they ask us now)
> >     Suggested Home Page Announcement:   (for the comm team to use or rewrite)
> >     Maturity:   (unless pubrules-checker can be fixed to guess it right)
> >
> >     [SUBMIT]
> 
> There are other bits to be provided and/or checked:
> 
> * Markup Validator, CSS Validator, Link-checker, etc.
> * history of the spec
> * patent policy
> * ...
> 
> >
> > After you press SUBMIT, and the information is queued, you'll be
> > redirected to
> > http://www.w3.org/2012/pubstatus?user=...&shortname=---&date=....
> > where you can see how it's progressing.  You'll be told how it's doing
> > on all the checks.   If it passes them all, it'll wait in the queue
> > until the given time is reached and then immediately appear on /TR.
> > Hopefully comm can keep up with the home page announcements, but that's
> > a separate issue.
> >
> > How's that sound?
> >
> > If it gets stuck, you ask webreq.    Webreq becomes tech support for
> > publication, with nothing to do on days where things are going well.
> 
> I don't think people really understand why things are slow... 

People, or me?    The part of the situation I don't know is what kind of
errors people typically make outside my own WGs.   In my groups the big
thing that tends to slip by and get to the Webmaster is broken links.
This may be due to the reprehensible 1-second-per-link delay in the link
checker which makes people not bother to recheck links after every edit
while converging on publication.    I believe my proposal addresses
problems like this.

BTW, a propos of nothing, where is the source to the link checker
currently installed?  :-)

>
> There
> are two main reasons for this to happen:
> 
> 1. getting a spec pubrules-compliant
> 
> Most editors don't know the full W3C process.  They don't read the
> main document explaining it.  And they shouldn't, because it's
> complicated and error-prone.  They should rely on tools that work, but
> the current ones (pubrules checkers and other validators/checkers)
> fail at explaining simply and precisely why things are not ok in some
> cases.

Agreed.

> In that regard, I believe that Philippe's proposal goes into the right
> direction, as the idea is to remove as much checking as possible, and
> to generate the missing bits from some precise data (much easier to
> check).

>From the perspective of a user who is happy to use ReSpec -- ie most new
users -- my proposal has all the advantages of Philippe's.   The user
writes the document using ReSpec and publishes it as desired with little
more than a click.   My approach has several advantages, including
(relevant here) the fact that it will catch lots of document problems
the can slip by ReSpec, or be introduce by ReSpec if someone doesn't
configure it properly.

> 2. non compliant specs need interaction with the Webmaster
> 
> That's actually the biggest issue, as it involves back-and-forth
> between humans working on other projects, under different timezones,
> etc.
> 
> Because of these constraints, W3C has put a schedule in place
> (Tuesdays and Thursdays) to get people more organized, asking them to
> submit *checked* documents at least one day in advance, in order to
> fix the remaining failing parts.  Even the most experienced editors
> make mistakes...
> 
> That's why the editors are asked to make an appointment with the W3C
> Webmaster. So if the proposal makes point 2. being still mandatory,
> then I believe that we haven't improved the situation.

Thus my point: automating the mechanical-checking function of the
Webmaster would speed things up, and offload the Webmaster to do more
tech support / hand-holding.

> > One cool feature might be that xmlspec and respec input files could be
> > submitted and the system would do the right thing, as if it were a Web
> > Browser.  That would be nice.   Not sure whether to use something like
> > selenium, or xsltproc and node+jsdom.
> 
> Please remember that there will be people implementing the fully
> automated checker.  And there will be people using it as well.

Are you trying to suggest that what I'm asking for is too hard to
implement?   Or too hard to use?   I think the implementation cost is
worthwhile, and *by definition* it's no harder to use than the current
system, since the user could always fall back on tech support (the
webmaster) to fill in the form for them.

> Because of these reasons, I would propose to go for *only one way* to
> do things.  Accepting alternatives in specs is one of the main reasons
> for the current tools not to work very well.  JSON is a viable option
> here.  There is nothing preventing us from generating metadata in
> other formats during the actual publication, if we feel the need for
> it.
> 
> >
> > For permissions, there are several options.  Maybe only W3C staff can
> > press SUBMIT.   That would be easiest (and you could do without the
> > "user" parameter), but read on.
> 
> That will depend on the requirements that W3C will put on the
> documents.

I don't know what you mean.   I'm not suggesting W3C change the
requirements it puts on documents.  

Re your proposal: I don't see how requiring everyone use ReSpec would
affect the permissions needed to publish.

> > What I'd really like would be that
> > ANYONE can press submit -- but it remains in the queue until
> > appropriately endorsed.
> 
> I guess we all want that :-)
> 
> > If it's a FPWD, CR, PR, or REC it would need approval from a chair,
> > staff contact, and a w3m'er.   (The people are not so much approving the
> > document, as certifying that correct process has been carried out.  The
> > chair is saying the WG has resolved to publish, not saying they
> > personally approve of the document.)
> >
> > If it's an OWD or LC or NOTE (after prior FPWD), it would only need
> > approval from a chair and staff contact.
> 
> I agree on the principles, but this will need to be fully documented.

I'm not a big fan of systems needing documentation.

> And tested.

Yes, but for most of the system the failure modes are only:

1 - a spec gets through which shouldn't have -- but that already
happens; I believe this would reduce the rate, because of increased
automation in the process

2 - a spec gets rejected by the automated tests and needs a human to
over-ride the tests -- but that already happens, too.

Of course there are some bits where the code needs to be quite solid.

> > I suggest that ED be allowed, too.  That would need no approval.   I
> > suggest ED's appear at a URL based on the submitters userid and the
> > shortname they suggested, like:
> > http://www.w3.org/editors-draft/21507/my-pet-spec-20120430
> > with a "latest version" at
> > http://www.w3.org/editors-draft/21507/my-pet-spec
> 
> Adding nice-features-to-have won't help people to implement the
> tooling, I'm afraid.  

I don't agree.  Giving people new and exciting functionality to shoot
for makes it much more appealing to people who care about this stuff,
which means it's going to be done sooner and better, at least if it's
done by people who care about this stuff.

> We need to stay pragmatic and think about a
> system that would get *all* the editors on board.

The only way we're going to get all the editors on board is by not
giving them any new mountains to climb.   The only burden I'm giving
them is to fill out a web form instead of composing email to the
webmaster, ... and in return for this they get a host of good things.  

I think you're proposing they throw out person-weeks of software
engineering in spec production, unless they happen to be using ReSpec.

> Anyway, I believe that Philippe's proposal is a pragmatic start.

Except that it doesn't actually improve the situation at all, since (as
others have pointed out) it's a non-starter to require every pub to use
ReSpec.

    -- Sandro

> Alexandre.
> 
> >
> > Cool, eh?  No more Editor's Drafts in a hundred random locations, with
> > no change tracking or anything.   Maybe the system can offer convenient
> > diffs.
> >
> > Ideally, everything would start as an ED.  The WG would approve
> > publication of a given ED and the system would do the necessary
> > transformations to turn it into a TR, with no need for human hands (or
> > human error).  That would be cool, but would require more getting into
> > the guts.  (In particular, the system would need to be able to change
> > the publication date on several documents that all link to each other.
> > Also, there would need to be an allowance for small changes being made
> > even after some approval stages, vetted by someone.)
> >
> > That'd be nice, huh?
> >
> >       -- Sandro (who handed the webmaster three more TRs today, one
> >                  respec, one xmlspec, and one hand-written html)
> >
> >
> >
> >
> >
> 
> 
Received on Tuesday, 8 May 2012 16:09:24 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 May 2012 16:09:25 GMT