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

Sending Liam Quin's comments below.
Reply-to set to: liam@w3.org, public-w3process@w3.org

Cheers,
Coralie

------- 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.

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)

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?

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?

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.

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.

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)

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...

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.

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?

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

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.

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

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" :)

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".

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

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.

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.

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

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"??

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

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.

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.

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

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

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?

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", 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)


"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).

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.

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

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?

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.

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?

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! :-)
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?
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) how would such a change
not also be one that "turns conforming data, processors, or other
conforming agents into non-conforming agents"? 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.

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

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"

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

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?

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.

Thanks,

Liam


-- 
  Coralie Mercier  -  W3C Communications Team  -  http://www.w3.org
mailto:coralie@w3.org +336 4322 0001 http://www.w3.org/People/CMercier/

Received on Wednesday, 19 March 2014 22:48:21 UTC