Discussion page: Errata in IVOA standards

Obsoleted by DocStd13

There is a need to set up the possibility to have errata for IVOA standards. This would require an amendment to the IVOA Document Standard http://www.ivoa.net/documents/DocStd/20100413/. This page is set up as an action decided at the TCG telecon held 17 December 2013 to gather TCG comments on the initial proposed amendment text, as a first step towards a modification of the Document Standard.

Deadline for TCG comments: 31 January 2014

Here is the proposed addition:

Add a section 1.6, "Errata", with the content:

As necessary, a Recommendation can be accompanied by an Errata page in the IVOA document repository. Errata pages are versioned, i.e., REC-1.0 and REC-1.1 will have different sets of Errata.

Errata may not be used to change the normative content of a Recommendation. They are intended both to allow corrections of non-normative material (examples, typographics, clarifications), and raise attention to specific issues with a recommendation together with a recommendataion to its resolution. Examples for the second type of Erratum include contradictions with other Recommendations, internal contradictions, or severe obstacles to implementation that have not been identified during the standardization process.

Errata can be proposed to the chair or vice-chair of the Technical Coodination Group (TCG), who circulates the proposed Erratum on the TCG mailing list. Every member of the TCG may veto the treatment of a piece of text as an Erratum on grounds that it introduces normative changes; if no veto has been brought up within two weeks, the Erratum is published in the IVOA document repository alongside the Recommendation.

At every session, the Executive Committee reviews the Errata accrued since the last session. The Executive Committee can withdraw an Erratum with single majority. Such Errata will be marked as withdrawn in the document repository, possibly with a reference to a superseding Erratum.

Please enter your comments below

While not on the TCG proper, I was already involved with this discussion so I hope my comments can be taken into account.

I am uncomfortable defining a voting rule of simple majority, or anything other than consensus, since the Exec has always worked by consensus rather than some specific type of majority vote. Let's please not introduce that for something so simple as Errata.

Rather than "Every member of the TCG may veto..." I'd suggest "Any member of the TCG may veto...".

I also think that the Document Coordinator should be consulted, as the suggestion that "the Erratum is published in the IVOA document repository alongside the Recommendation" may be non-trivial to implement, especially if the current system is eventually replaced with something more automated. Overall this is my main concern about Errata, that is, that they do not get overlooked.

-- BobHanisch, 18 December 2013

I believe this process is too formal for Errata. I will suggest some alternatives/additions:

- All new standard documents will automatically be assigned a page on the IVOA wiki for Errata. The link will be clearly shown in the document itself, in a prominent position, and in the IVOA documentation page.

- For old documents, create a new wiki page for errata only if necessary, and change the document for the only purpose of including the link to the errata page (to be honest, I am not sure about this one, but we need to define some process for old documents).

- Errata can change over time: most likely, new errata will be added, but it might happen that a new erratum may supersede an old erratum. In this case I suggest to edit the wiki page to strikethrough the old erratum, and reference its ID in the new erratum. In addition, wiki revisions can be used to track the changes to the erratum page.

- By the way, each erratum should have an ID string, so that it can be referenced.

- I agree with Bob on the simple majority: an error should be trivial to describe and agree upon. If the erratum is contentious and there is no consensus, then it is unlikely to be an error in the first place, and the change should be addressed using the usual standardization process.

-- OmarLaurino - 2013-12-18

Pierre LeSidenar and I have had some follow-up discussion and both have similar consideration to include the Errata in the same document standard and not an ancillary doc which requires additional retrieval and maintainance (both for source and user). This is especially important for the document end user that they have all the available information for the standard to interpret the Errata/change to document.

Complications with having to read and obtain multiple documents to provide the complete picture which perhaps serves as an intermediate solution vs. restarting the full standards process, in my view is less optimal than including the Errata within the document

With the WG input and TCG review of Errata content, non-major standard version document updates would be feasible

-- GretchenGreene, 18 Dec 2013

[I note for reference that the email thread leading to this suggestion can be found in the Dec-2013 DAL list archive under the subject "TAPRegExt erratum, Identifiers for Obscore".]

Personally I favour Errata as a document separate from the numbered REC document itself. If it's done like this then there is only one version of the REC document, and if you have that in front of you (possibly printed out) you know you don't have an out of date copy. Incorporating errata into the document itself raises questions of whether the document version number or document date changes, to which the answers are not obvious. Also, rebuilding and resubmitting the document with additions (and possibly date/version number changes) is not necessarily easy. In the case of some of the older documents where the document source code, or the platform on which to build it (e.g. old version of Word?) is no longer available, it might be all but impossible, or result in formatting changes that mess up page references etc.

Agreed having a separate Errata document does increase the chances of readers failing to notice the errata, but we've been doing without errata (or any lightweight process for updating documents with corrections) altogether for the last decade, and this will be an improvement on that.

As Omar pointed out during the email discussion, a separate Errata page is how the W3C (from whom we have lifted most of the rest of our document standards) handle this: see http://www.w3.org/2001/06/manual/#Errata. The detailed prescription described at that link for how to write an erratum entry also looks sensible to me.

-- MarkTaylor - 2014-01-08