Re: Draft Replacement Text for Section 7.7.1 Errata Management

Very nice.

I would like a short note inserted pointing out that not all this work has to be manual.


On Nov 2, 2014, at 2:47 , Stephen Zilles <szilles@adobe.com> wrote:

> At its 14 October 2014 Telcon, the Process Document TF identified 3 issues with the description of Errata Management:
> 1.      Working Groups are not always being responsive and updating the errata associated with a Recommendation. It was agreed that Working Groups  SHOULD process any comments that could generate an erratum no less frequently than quarterly. And, that the ideal would be near continuous updates
> 2.      The current description is a bit fuzzy on what changes can be used in a Proposed Errata. This can be cleared up by referring to the 7.2.5 Classes of Changes where errata would include any of the first three classes of changes. Item 37 of the Patent Policy FAQ [1] allows a WG to fix broken links and invalid markup, make editorial clarifications, and make substantive corrections provided they introduce no new features. [These are exactly the changes in the first three classes of section 7.2.5.]  The process involves community review of a "Proposed Edited Recommendation" that is subsequently published as a new edition of the same Recommendation. Licensing commitments made to the original Recommendation will apply to new editions that result from this process.
> 3.      Currently, errata are required to be on a separate “errata page” that is pointed to from the Recommendation and that page should have a list of the errata together with any proposed correction that fixes the erratum. This means that a reader of the Recommendation has to go to the errata page and (mentally) update the Recommendation text with the content of the Proposed Correction. This seems to fail in practice. Therefore, it was proposed that Recommendations be allowed to be update with the Proposed Correction going to the appropriate place in the Recommendation provide that: (a) a viewer can view just the content of the recommendation without any Proposed Corrections, (b) the content with the Proposed Correction in place, and (c) the actual change that the Proposed Correction makes. These views should be robust under printing the document with a bi-color printer. See the proposal [2].
>  
> [1] http://www.w3.org/2003/12/22-pp-faq.html#edlicensing
> [2] http://lists.w3.org/Archives/Public/public-w3process/2014Oct/0139.html
>  
> Below is first the 7.7.1 text from Process2014, then the proposed replacement text follows and finally comments on that replacement text end this message.
>  
> Current Text
> 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 class of mistake, from mere editorial to a serious error that may affect the conformance with the Recommendation by software or content (e.g., content validity).
>  
> Working Groups must track errata on an "errata page." An errata page is a list of enumerated errors, possibly accompanied by corrections. Each Recommendation links to an errata page; see the Team's Publication Rules.
>  

(Note that such a page may be an auto-generated list list bugs or issues that the working group has consensus represent errata in the specification.)

> A correction is first "proposed" by the Working Group. A correction becomes part of the Recommendation by the process for Revising a Recommendation described in the next section.
>  
> A Working Group should keep their errata pages up-to-date, as errors are reported by readers and implementers. A Working Group must report errata page changes to interested parties, notably when corrections are proposed or incorporated into an Edited Recommendation, according to the Team's requirements.
>  
> Replacement Text
> 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 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.
>  
> Comments on the proposed replacement text
>  
> 1.      The paragraphs have been re-ordered to have definitions precede their use
> 2.      I tried to be careful on terminology, trying to distinguish “erratum” (error) from the “proposed correction” (which fixes the error) because these do not always occur simultaneously and may evolve (within a document) over time.
> 3.      As was pointed out in the Process breakout session at TPAC, the timeliness constraint (no less frequently than quarterly) applies NOT to forcing a publication, but to responding to comments and bugs filed on the Recommendation. If these are deemed to generate errata (and proposed corrections) then the relevant document should be updated as well as part of the response.
> 4.      I have dropped the notion of an “errata page” because some have suggested that the errata link point to a version of the editor’s draft that highlights errata and others have suggested showing the errata in place in the Recommendation.
> 5.      The handling of issues 1. and 2. above was relatively straightforward. I believe that I have been less successful with issue 3., finding a way to express reasonable constraints on how “errata are placed in the Recommendation”. The problem is that the existing 7.7.1 text is too specific; it specifies an “errata page” and, to some extent, “how that page should look”. This seems over constrained. But, allowing updates to the Recommendation in place, which is what a number of WGs would like to do, should be constrained to at least allow a viewer of the document to see what is normative (in the approved Recommendation) as well as what  are (informative) proposed corrections. They stay informative until a Revised Edition is issued. I have made an attempt at these constraints, but am not very happy with the results.
>  
> Steve Zilles

David Singer
Manager, Software Standards, Apple Inc.

Received on Monday, 3 November 2014 10:32:19 UTC