Re: errata again, responding to the november proposal

Hi

my issues with the proposed text:

a) it is NOT ‘the recommendation’ but a document using the Recommendation as a basis, if inline reporting and editing are done.
b) This assumes only one way of working — editing in-place.  I think the old model is workable (manual errata page) and a model with a list of errata auto-generated from a database (e.g. issues, bugzilla) is also workable.
c) I have no idea who ‘interested parties’ are for the must requirement in the last paragraph, so I don’t know how it’s testable. In fact, what is this paragraph trying to say or do?

So, here are my ‘minimal' changes.



7.7.1 Errata Management

Tracking errors is an important part of a Working Group's ongoing care of a Recommendation; for this reason, the scope of a Working Group charter generally allows time for work after publication of a Recommendation. In this Process Document, the term "erratum" (plural "errata") refers to any error that can be resolved by one or more changes in classes 1-3 of section 7.2.5 Classes of Changes.

A Working Group must keep a record as errors are reported by readers and implementers. Such error reports should be processed no less frequently than quarterly. Readers of the Recommendation should be able easily to find and see the errata that apply to that specific Recommendation.

Working groups may decide how to document errata. Examples of acceptable errata management include an errata page, possibly auto-generated from a database, or a document that identifies itself as based on the Recommendation text and clearly identifies the errata and any proposed corrections.

An erratum is resolved by an informative, "proposed" correction generated by the Working Group  A correction becomes a normative part of the Recommendation by the process for Revising a Recommendation described in the next section.

A Working Group must report changes that incorporate errata to interested parties, notably when corrections are proposed or incorporated into an Edited Recommendation, according to the Team's requirements. [[huh??]]



> On Jan 13, 2015, at 10:25 , Jeff Jaffe <jeff@w3.org> wrote:
> 
> 
> On 1/13/2015 12:12 PM, chaals@yandex-team.ru wrote:
>> Hi,
>> 
>> I took action-141 because I disagreed with Steve's November proposal for errata [1]. In today's meeting Steve asked us to respond to that proposal and explain objections and changes that would address them.
>> 
>> The proposed replacement text for section 7.7.1 is [[[
>> Tracking errors is an important part of a Working Group's ongoing care of a Recommendation; for this reason, the scope of a Working Group charter generally allows time for work after publication of a Recommendation. In this Process Document, the term "erratum" (plural "errata") refers to any error that can be resolved by one or more changes in classes 1-3 of section 7.2.5 Classes of Changes.
>> 
>> A Working Group should keep their Recommendations up-to-date as errors are reported by readers and implementers. Such error reports should be processed no less frequently than quarterly and errata should be placed in the Recommendation.
>> 
>> An erratum is resolved by an informative, "proposed" correction generated by the Working Group  A correction becomes a normative part of the Recommendation by the process for Revising a Recommendation described in the next section.
>> 
>> There are two ways in which the errata and/or proposed corrections may be placed in the Recommendation. First, the Recommendation may point to a page in which the errata (and any proposed corrections that fix the erratum) are incorporated in an identifiable way. Alternatively, the Recommendation may be edited to allow a viewer to selectively display: (a) the original content of the Recommendation, or (b) that content updated to show the corrected text. Either of these approaches MUST satisfy the then applicable Publication Rules.
>> 
>> A Working Group must report changes that incorporate errata to interested parties, notably when corrections are proposed or incorporated into an Edited Recommendation, according to the Team's requirements.
>> ]]]
>> 
>> Responding paragraph by paragraph:
>>  1. The first sentence boils down to "bugs have to be tracked when you find them, even after recommendation". I agree that the process should set that expectation. The second sentence attempts to define errata specific to W3C process, because that distinction is used later in the proposal. I do not think that defining them specifically is useful, and as explained below I do not think the use for the specific definition is helpful.
>> 
>> 2. The first sentence assumes that a Recommendation belongs to a Working Group, which is false.
> 
> I agree that a clarification would be helpful.  Perhaps something like:
> 
> A Working Group should make it easy for the community to find errors reported by readers and implementers together with suggested corrections.  A best practice would be to create a document which contains suggested corrections alongside the original Recommendation text; with clear markings (e.g. different colors) what is the Recommendation text and what are the suggested corrections.
> 
>>  A Recommendation is a Recommendation of the W3C developed through a consensus process. The Working Group does the "grunt work" of proposing what that should be in detail, but it is not a W3C Recommendation. That said, the process is intended to allow W3C to produce Recommendations that are useful - and this means that for the lifetime of a technology it is probable that there will be value in providing corrections, enhancements, etc. That is the point of being able to revise a Recommendation, and the fact that it should happen is already covered in the first sentence of paragraph 1.
>> Specifying a particular rhythm is saying in another way what is in 7.2.1 (we could just link there).
> 
> I don't see the harm in listing the quarterly expectation here.
> 
>>  I strongly object to the suggestion that errata (statement and/or proposed resolution) should go directly into a Recommendation, rather than some other document such as an errata list, bug tracker, draft replacement version, etc. (I'll return to this in regards to paragraph 4).
> 
> I believe that the intent was that it would be a draft replacement version.  Clearly the text that has not been through the process does not rise to the level of Recommendation text.
> 
>> 
>> 3. This paragraph doesn't add anything useful, and could be scrapped. There is an existing discussion of how issues are resolved, and a "proposed" correction is merely an attempt to provide a formal title to a proposed resolution of a bug or issue.
> 
> Fair point.  I believe that the purpose of this paragraph was merely to emphasize that the text of a proposed correction (when it sits in one of these "draft replacement versions" - or whatever we call them) does not have Recommendations stature until it goes through the Revision process.  There are probably editorially superior ways to phrase this; especially in view of the comments above.
> 
>> 
>> 4. There are at least 3 useful ways to track issues raised against a document, and the proposals made, and accepted by the working group, to resolve them. Putting them into an errata list, putting them in a bug or issue tracker, and putting them into a draft document are all reasonable alternatives. None of them involve touching the text of a W3C Recommendation.
> 
> I think these are all reasonable ways to track issues and what is accepted by the WG.
> 
> The input that the task force received last year was that the particular idea of threading the proposed changes into the Recommendations text would be of particular value to readers.  That was the proposal that we went with earlier.  I think this should at least be identified as a best practice.
> 
>>  In addition, setting a constraint for "classes 1-3 of change" (as defined in section 7.2.5, i.e. those which do not involve a new feature [2]) but requiring that it not be applied to class 4 (new features) introduces a layer of busywork for a group that has a sensible way of updating documents in a timely manner and informing people of changes they are proposing for the specifications they manage.
> 
> Whether or not this is busywork depends a fair bit on how quickly the group can get out new features.  We don't have a great track record for new features (HTML took over 10 years) so being more agile for classes 1-3 seems essential.
> 
>> The second sentence is reasonable as *a suggestion* for ways to manage errata. Although there are many situations where that approach has been found to be problematic, meaning it should not be *mandated* there are also ways to use it reasonably, meaning it should not be forbidden.
>> Proposing to incorporate new material that has not been reviewed by W3C into a Recommendation strikes me as an incredibly bad idea. W3C has long maintained a social contract that the text of a Recommendation will not change. Publishing them as static documents without multiple viewing options is an important part of ensuring that there is not confusion about what is the text of the Recommendation. Changing that seems a terrible idea. Publishing e.g. an editor's draft for a replacement version (something that W3C has also been doing for almost a couple of decades), or using some other means of tracking proposed changes that have not been approved by W3C, and clearly linking it from the Recommendation, seems a perfectly adequate mechanism of informing people about the latest ideas while providing a simple, reliable and stable reference for those who need one.
> 
> Some of this argument is one of semantics.  I see tremendous value in the proposed idea of embedding the current thinking about proposed changes into the text of the Recommendation.  For my pov, we don't need to call this a Recommendation at all.
> 
>> In addition, while there are various mechanisms to identify two different views of a single document, such as the use of extra styles, they are less reliable than simply having two different documents e.g. a Recommendation and an Editor's Draft. In any event, where there are class 4 changes being proposed at the same time, it makes no sense to *require* a version that does not make them available while presenting class 1-3 proposed changes.
> 
> See above.
> 
>> 
>> 5. The requirement to inform "interested parties… according to the Team's requirements" is redundant with the requirement in the subsequent section 7.7.2 (first bullet in the list in that section), but without the explanation of what that means which is provide for the term "wide review".
>> 
>> To summarise, the features of the proposal I explicitly object to are
>> - Anything that suggests adding material to a published Recommendation (as opposed to an Editor's draft or other separate document with a different status)
>> - Redefining the term "errata"
>> - Forcing groups to use different mechanisms for different types of issue, beyond constraints in the existing process outside section 7.7.1
>> - The use of different text from elsewhere in the document in the final sentence
>> - The verbosity of the section
>> - Constraining the way groups present issues and proposed resolution of them beyond the existing Process outside section 7.7.1
>> 
>> The parts that I find neither objectionable nor unnecessary repetition are
>> - a statement that publishing a Recommendation doesn't mean the responsibility of a working group to record and address issues has been discharged.
>> - allowing the use of an errata page as one means of tracking issues raised against a Recommendation.
>> - the idea (implicit but unstated) that it should be easy to find the issues raised against a recommendation and solutions proposed for them.
>> 
>> It seems that these three points could be more succinctly expressed in a single introductory paragraph, and we could remove section 7.7.1 and the section 7.7.2 header entirely header If people like that idea, I will propose some specific text.
>> 
>> cheers
>> 
>> [1] https://lists.w3.org/Archives/Public/public-w3process/2014Nov/0004.html
>> 
>> --
>> Charles McCathie Nevile - web standards - CTO Office, Yandex
>> chaals@yandex-team.ru - - - Find more at http://yandex.com
>> 
> 
> 

David Singer
Manager, Software Standards, Apple Inc.

Received on Wednesday, 14 January 2015 21:24:10 UTC