Re: Feedback from Liam Quin - Fwd: Re: Staff contacts review of draft Chapter 7 revision

Hi Liam,

On Wed, 19 Mar 2014 23:48:11 +0100, Coralie Mercier <coralie@w3.org> wrote:

> ------- Forwarded message -------
> From: "Liam R E Quin" <liam@w3.org>
> To: "Coralie Mercier" <coralie@w3.org>
> Subject: Re: Staff contacts review of draft Chapter 7 revision
> Date: Wed, 19 Mar 2014 23:34:10 +0100
>
> On Wed, 2014-03-19 at 17:06 +0100, Coralie Mercier wrote:
>> Hi Staff contacts,
>
> [...]here are some comments. I love the diagram. Feel free to
> forward this to Charles or wherever it should go.

Thanks for the comments.

Can you say what version you reviewed, since it seemed not to be the  
current one even when you sent this.

In several cases I have apparently rejected your comments - i.e. I don't  
propose to do anything with them. If you want an issue raised, feel free  
to do it in the w3process tracker. Where I believe there is an issue I  
will raise one myself, as noted inline.

For really editorial comments, I will just make changes and produce a new  
draft, I hope tomorrow.

> Note, I read the document once from start to end and made notes as I
> went - some of the notes might have been changed if I read the document
> first and then made notes on re-reading, but maybe it's actually more
> useful like this.
>
> 1. (intro) "There is a requirement that Working groups should document
> known implementation for all transitions" there is no such thing as a
> SHOULD requirement. It's a suggestion. It sounds like a good one but it
> needs to clarify known by whom and howmuch work the WG is expected to do
> to find implementations. (e.g. once a year or so I come across an XQuery
> implementation entirely done outside the WG that none of us knew about,
> most often used inside a product or an organization)

This material is not present in the latest draft. But describing the  
strength of a statement marked SHOULD is ultimately an editorial  
judgement. I'll raise an issue to clarify it, whatever it is.

> 2. "Every document published as part of the technical report development
> process must be a public document" does this mean no more Member-only
> working groups?  Or does it mean the documents must be public after
> being published?

"Published" in the document means put on /TR. So it has nothing to do with  
how groups
choose to develop their work.

I'll check that this meaning is

> 3. "W3C will make every effort to make archival documents indefinitely
> available at their original address in their original form."
> Does this preclude updates to links or editorial changes (fixing a typo)
> that are currently permitted?

Covered already in classes of change.

> 4. "Every document published as part of the technical report development
> process must clearly indicate its maturity level, and must include a
> section about the status of the document."
> What about documents that are already on /TR and are not yet at Rec?
> Their maturity level indicators will now be misleading, but the previous
> sentence says we won't change documents on /TR.  Therefore, we should be
> careful never to change the meaning of a maturity level.

Why would they be misleading? The changes are that "Last Call" goes from
having a defined meaning to being a historically meaningful term, and
Candidate Recommendation assumes a certain amount of that meaning. All
documents are published with a date, and a pointer to the operative
process document, but even so, the practical differences seem unimportant
to understanding what you are getting.

> 5. "should explain how the technology relates to existing international
> standards and related work inside or outside W3C"
> I believe that this would be better done with separate Overview
> documents that have a different life-cycle.

Perhaps. Whether a document is a stand-alone document or a set of
documents bundled together is an implementation decision. And this is a
should - having a seperate doc would be a justification for ignoring it as
redundant IMHO.

> 6. "should explain or link to an explanation of significant changes from
> the previous version"
> I'd like to see this remain a MUST (at least, it's enforced more or less
> as a MUST today)

Me too, but that wasn't the decision we reached... (unless I messed up as
editor).

> 7. "An editor must be a participant, as a Member representative, Team
> representative, or Invited Expert in the Group responsible for the
> document(s) they are editing."
> This could be read as excluding e.g. a hired professional writer from
> editing a document, i.e. that in order to be called an editor, a person
> must be a WG participant; or it could be read as meaning "at least one
> of hthe editors must be a WG participant". In either case we could not
> (publish XPath with this rule, because it's developed jointly with two
> Working Groups. I know, I know, I'm being pedantic, but if we are
> writing a process to cover what we do, etc etc...

Yeah, there are several situations where this (existing) process
requirement is violated. It isn't clear to me that the rule should be  
changed, although it is also unclear how to publish a document jointly.

This is probably worth addressing seriously, although I believe it is  
orthogonal to any changes made so far, and could be done in a revision  
along with other changes to the Process.

> 8. "Note: Last Call Candidate Recommendation is the state referred to in
> the W3C Patent Policy [PUB33] as "Last Call Working Draft"
> No it isn't. lCCR didn't exist when the patent policy was written. I'm
> not sure what is meant here, but I think it's, "A specification at Last
> Call Candidate Recommendation shall be considered to be a Last Call
> Working Draft for the purposes of the patent Policy [ref]." But LCCR is
> certainly not what was meant when the patent policy was drafted. This is
> obvious to us now, but not to someone outside W3C.

OK. I believe this is editorial but a good suggestion. I'll make the  
change.

> 9. What is meant by "Note: Last Call Candidate Recommendations will
> normally be accepted as Recommendations."? Does that mean that once we
> get to Last Call Candidate Recommendation we've also reached
> Recommendation? If so why is W3C Recommendation a separate step?

No, it means that they will *normally* be the same content. The separate
steps represent a few checks that attempt to avoid publishing things as
Rec that we will regret later.

> 10. "to >provide a stable reference" typo (there's also an extra comma
> in that sentence before "but" I think)

Fixed.

> 11. "Working Groups and Interest Groups may publish "Editor's drafts""
> Currently some groups publish these outside /TR; the Process should be
> explicit about whether this is OK and under what circumstances.

As far as I am aware, and by definition "Editor's drafts", as opposed to  
Working Drafts as defined by the Process, are all published outside /TR.

> 12 "Because the requirements for First Public Working Drafts are fairly
> mechanical approval"
> a comma before "approval" may help this sentence :)

statement was changed.

> 13. "A substantive change" (7.2.1, definition) - this is an area where
> I'd like to see the Process give more guidance. For example, for a
> document format such as SVG, XQuery or HTML,
> . is it substantial if users have to change their documents?
> . is it substantial if legal documents are unaffected, but error
> processing of non-conforming documents is changed?
> . is it substantial if implementers have to change code, e.g. of an SVG
> renderer?
> . is it substantial if the code and the documents and the end result are
> in all cases unchanged but the document is rewritten?
> In practice a case-by-case decision probably has to be made, but the
> sentence "larifications, bug fixes, editorial repairs, and minor error
> corrections" suggests that some some changes that are not editorial are
> also not substantive. E.g. "it was a bug that <blink> was included" :)

I *believe* this section has been rewritten since this comment,  
invalidating the comment.

The document uses the phrasing "data, processor or other agent" and  
defines substantive change as any thing that changes the conformance  
status of any of these.

While in practice there are possible cases that would need to be judged by  
a human, I don't think it is worth the effort to anticipate them and try  
to prejudge them in the written process.

If you believe there are clear cases beyond what is now in 7.2.5. that  
should be defined, please raise an issue.

> This comes back again in 7.3, "Working Groups are often reluctant to
> make substantive changes to a mature document, particularly if this
> would cause significant compatibility problems due to existing
> implementation." suggesting that some level of minor incompatibility is
> not considered substantive.
>
> 14. "W3C follows these steps} [...] "Possibly, Publication as an Edited
> Recommendation"
> Suggest expanding that to a separate paragraph, If the need arises to
> incorporate errata or change a Recommendation for other reasons, a new
> edition may be produced as an Edited Recommendation".

I prefer to leave the details to the relevant section (as with the rest of  
the list of steps).

> 15. These steps do not include Proposed Edited Recommendation - is the
> omission deliberate?

Which steps?

> 16. the list of maturity levels does not include Proposed
> Recommendation, nor Edited Recommendation, and presumably should.
> Currently, 7.4's ordered list is the first mention of Edited
> Recommendation after the table of contents.

Was fixed.

> 17. "The Director must inform the Advisory Committee and Working Group
> Chairs when a Working Group's request for a specification to advance in
> maturity level is declined"
> It would make sense to require that the reason for the refusal is also
> disseminated to the AC and Chairs. For a public WG it should also be
> made public.

I'll raise an issue. I agree with the proposal.

> 18. "7.4.1.a First Public Working Draft" (the "a" here would be less
> confusing with a dot after it.)

The numbering changed - no more "a".

> 19. "must record the group's decision to request publication. Consensus
> is not required, as this is a procedural step"
> This needs a definition of "procedural step". I have no clue what is
> meant here or why consensus to publish isn't needed, or how you can have
> a WG decision recorded if there was no consensus to make the decision -
> do you mean just "If the WG does not have consensus to publish, the WG
> chair or chairs may go ahead and publish anyway"??

The chairs must record a decision. It is not required that it is a  
consensus decision.

Which in extremis does allow chairs to go ahead and publish. In a group  
that is sufficiently dysfunctional that this is a problem, whether it  
publishes a Working Draft is not one of the important problems.

> 20. "Revised Public Working Draft" is not one of the maturity levels in
> the list of maturity levels.

It is a Working Draft. This was editorially clarified already.

> 21. I note that neither "7.4.2 Last Call Candidate Recommendation" nor
> "7.4.3 Publication of a W3C Recommendation" explicitly requires sign-off
>   from other Working Groups mentioned in the WG charter or charters (for  
> a multiple-WG document) as having formal liaisons. This may help to speed
> up the process but I am not sure it's an improvement.

Generally, a group would be expected to show as part of wide review that  
it has got agreement from groups which are listed as having formal  
liaisons or dependencies. The group is specifically required to state any  
changes to dependencies at transition.

> 22. "To publish an Edited Recommendation as a W3C Recommendation" I
> don't think this is right. I think you mean, "To publish a Last Call
> Candidate Edited Recommendation as an Edited Recommendation" but given
> the lack of definitions of these terms I can't be certain.

I actually mean to say that you can publish it as a Proposed  
Recommendation without erturning to an earlier stage. I'll raise an issue  
on this.

> 23. "the general public, and must formally address the comment >at least
> 14 days before publication"
> (typo, extra > sign)

Not any more

> 24. Is it actually the Director who must address the comment, or the WG?

Where?

> 25. "The "Status of the Document" must reflect whether it is
> provisionally approved, or published as a W3C Recommendation."
> This document is introducing the concept of a W3C Recommendation with
> Provisional Approval as a new maturity level. I think I'm fine with
> that, and that it means you have inserted a step between Last Call
> Candidate Recommendation and Recommendation called Provisional
> Recommendation, but that means
> (1) you need a definition of this maturity level
> (2) the process must be clear on the transition requirements
> (3) any timing requirements need to be explicit;
> as staff contact I'll probably need to send a transition request from
> LCCR to ProvRec, and another from provRec to Rec, and we'll need to
> re-run the document build process, go through pubrules again, etc.
> What other changes can be incorporated into the document at this time?

This is moot. We reintroduced Proposed Recommendation to cover this.

> 26. Under 7.5 I see "In order to publish a Note a Working Group or
> Interest Group:
>       must record the group's decision to request advancement, and
>       should public documentation of significant changes to the technical
> report since the previous publication."
>
> but there is a missing pronoun. *who* "must record",

The Working Group or Interest Group that wants to publish it - the subject  
of the sentence.

> and if the WG is closed how can there be a group's decision to publish
> sa a note? This makes no sense (but it is why XSL-FO 2.0 is still a
> WD and note a Note, as the WG closed and there's neither a WG nor an
> editor)

In this case W3C is now required to (i.e. MUST) publish the Note. But as  
they are not the WG/IG they don't have to record a WG/IG decision.

> "A Working Group may resume work on the technical report at any time, at
> the maturity level the specification had before publication as a Note"
> Actually I don't think it makes sense to go from WG Note directly to
> Recommendation (e.g. if you had a PR when you closed the WG).

I believe that is an edge case not worth worrying about in practice. If  
W3C closes a Working Group with an unresolved Proposed Recommendation they  
deserve to have the problem of formally rejecting the PR and sending it  
back to CR and then publishing the Note.

Feel free to raise an issue if you (or anyone) thinks this is a problem  
that needs to be fixed.

> 27 Errata management
> "Note: Before a document becomes a Recommendation, the W3C Process
> focuses on substantive changes (those related to prior reviews). After a
> document has been published as Recommendation, the W3C Process focuses
> on those changes to a technical report that might affect the conformance
> of content or deployed software."
> This is the first mention of conformance of content and of conformance
> of deployed software (if that's what is meant). This is a new definition
> of substantive changes.

That was changed already.

> 28 "A Working Group should keep their errata pages up-to-date"
> What does this mean?

It means the Working Group, unless there is some good reason not to do so,  
is ordinarily expected to add reported errors to the errata page...

> 29 "Working Group must report errata page changes to interested parties"
> and "For instance, the Team might set up a mailing list per
> Recommendation where a Working Group reports changes to an errata page."
> This is interesting and not something I've encountered before.
> presumably the mailing list should be public (i.e. anyone can subscribe)
> and have public archives?

This whole thing is "...according to the Team's requirements." While I  
would love some consistency and clarity from the Team on that, as I  
understand the current requirements are "we don't really care enough to  
worry about this". Sadly, that seems OK to me for the present, as it  
apparently has been for the last decade.

> 30 "Classes of Changes to a Recommendation"
> Oh. It would have made the rest of the document a LOT clearer if this
> had been up with the definitions where it belongs! Please move it.

Yes. I agreed with you ages ago. After much discussion, it was moved.

> 31 "These changes include fixing broken links, style sheets or invalid
> markup" - is this intended as an exhaustive list? Is it only broken
> style sheets that can be changed? (this is the Web, they're _all_ broken
> and under construction! :-)) What about a style sheet change that uses
> the 'content' CSS property or that changes section numbering?

There is wiggle room for argument. Which means it falls on the Team to  
decide. I hope you do it consistently and transparently.

> 32. " Corrections that do not affect conformance"
> Um, we don't have a definition of conformance, and there is not (in my
> experience at least) consensus on what conformance means.
>
> 33. Ok, now we get to a definition of conformance, damn you Charles! :-)

I reject damnation except from verified saints from my approved list.  
Which is unavailable :P

> Hmm, no, we don't. It just looks like it. "turns conforming data,
> processors, or other conforming agents into non-conforming agents"
> . how do you turn data into an agent?
> . what does it mean to be conforming in the first place?
> . what is an agent?

clarified the editorial confusion.

> This text has some informal helpfulness but the difference between the
> first and third bullet points is unclear - how would a change to the
> specification " in such a way that an agent whose conformance was once
> unclear becomes clearly conforming or non-conforming" (I think you mean
> clearly conforming or clearly not conforming)

Although I believe the statement says what you think I mean, I could  
equally remove the "clearly". I'll do one or the other.

> how would such a change
> not also be one that "turns conforming data, processors, or other
> conforming agents into non-conforming agents"?

Example: When I wrote an SVG font in 1999, it was unclear from the (then  
draft) specification where exactly the change from zero-down to zero-up  
measurement on the Y-axis took place. Making that explicit may not have  
changed conforming processors into non-conforming, or vice versa, since  
until it was specified it is impossible to say if implementation  
(including content) was conforming or non-conforming based on where they  
assumed the change should take place.

> Well, if it made something conform that did not previously conform,
> so that's all the third bullet needs to say, I think - a change
> that relaxes a requirement for conformance.
>
> Overall I should say this section (7.6) is pretty clear and helpful, by
> the way.
>
> 34. "The modified Recommendation is published according to the Team's
> requirements, including Publication Rules [PUB31] and the Requirements
> for modification of W3C Technical Reports"
> So we go to http://www.w3.org/2003/01/republishing/ and find that only
> the *first* class of change and not the second are permitted.
> I *think* what is going on is that you are proposing relaxing this,
> consistent with current practice (fixing obvious typos, adding a
> non-normative note, etc being allowed). I support this, and would lke to
> see the "republishing" document updated too, of course.

the "republishing" document is something the Team wrote. The Process sets  
the rules, so it *should* be updated.

> 35. Under 7.7 Rescinding, "should document known implementation."
> s/implementation/implementations/

actually, either, I believe.

> 36. "In addition a Working Group proposing to rescind"
> add, after rescind, " a W3C Recommendation"
>
> and again after "In addition the Director, if proposing to rescind"

fixed

> 37. "comment >at least 14 days"
> typo, extra >

fixed

> 38. process bug
>
> In order to process an edited recommendation, a WG must show that the
> document has received wide review... (7.4.3)... *before* publishing it.
> How exactly do you do that?

However you want. Errata are public, the base document is public, the  
changes allowed in a PER are relatively simple ones. You can publish  
editors' drafts, delta specs, or make the case that the widely reviewed  
cvs diff meets the requirement, depending on the circumstances.

> 38 Agile
>
> I can see how the changes would have saved us approx. four weeks over a
> six-year period of development for XQuery 3.0 (no PR needed) but I am
> not sure that counts as Agile. Some of our WGs have added an additional
> step not required by the Process, WG-internal Last Call, that lasts
> several week but that saves a lot of time overall. More time than losing
> PR. I'm not sure there would be consensus on adding such an optional
> step to the Process document though.

I don't believe the new process will make Working Groups finish their work  
significantly faster, unless they are doing something wrong now and  
realise it when they read the new process.

The ability to make reasonable changes to a Candidate Recommendation  
without having to publish a new Last Call should remove a problem that  
Working Groups have complained about.

Most of the rest is an attempt to clarify the existing requirements and  
who has to do what, and make it simple for a working group to do its  
development in a tested-feature-driven agile manner, or in a totally  
traditional "waterfall" manner, or however it decides will be most  
efficient.

Groups are expected to publish regularly to TR, to get review, to have  
consensus on technical decisions and to ensure that their work is  
implementable in the real world, and has traction. That hasn't changed.

cheers

Chaals

-- 
Charles McCathie Nevile - Consultant (web standards) CTO Office, Yandex
           chaals@yandex-team.ru         Find more at http://yandex.com

Received on Tuesday, 22 April 2014 19:41:05 UTC