Identifying the locations of errata/corrigenda changes

[Dennis E. Hamilton]

I concur that the critical requirement is sufficient location information so
that the passage subject to any erratum/corrigendum change is unambigously
and *confidently* located.

It is therefore extremely valuable to establish sufficient context that
location of the "before" and the "after" are unequivocal and easy to place.
If the context is a bit excessive or redundant, that can be very valuable in
ensuring that the correction item is not itself in error, incorrectly
stated, or too easily misapplied.


 - Dennis

FURTHER OBSERVATIONS [NON-NORMATIVE [;<)]

 1. If line numbers were printed in the margins of pages, some but not all
of the difficulties around line numbering would have been alleviated.  If
section numbering had been taken to a fine level, whether or not reflected
in the table of contents (preferably not) there would also be more
reliability in locating passages even on documents with differing
pagination, although this is still not a cure-all when dealing with tables,
figures, code snippets, and examples.  

 2. When we were working on OASIS ODF 1.0 Errata 01, there was a lot of
recycling around getting the pages and line numbers right.  In a number of
cases there was no matchup and it took a while to make sure that the same
way of determining a line was being used for all items.  In a few cases, we
found that we corrected a place having the reported defect, but not the
place identified in the defect report (and there are problems with defect
reports not locating the relevant passage, or even section, precisely).  
   While this was a painful experience, it did catch problems where errata
items were too easily not locatable or easily mislocated.  
   My conclusion is not about reducing the difficulty of being so meticulous
but about the importance of having enough information that the accuracy of
the errata item can be inspected for and confirmed and that erroneous
application of the item is mitigated.

 3. I was at Sperry Univac at a time not long after some ex-Univac folk
founded Control Data Corporation.  There was a certain special tinge to our
competitive feelings about that, not unlike the one I noticed years later at
Xerox Corporation over the founding of and competition from Adobe.   
    One story that engineers at Univac liked to pass around was over the
lack of parity checking on the memory system of the CDC 1604 and other
products.  The way we heard it, attributed to Seymour Cray, was that parity
checking on the core memory then being used was not provided because of
false positives that resulted from failures in the parity-checking
circuitry.  The claim was that the memories were fine, it was the parity
circuits that were failure-prone.  I have no idea how apocryphal this story
is, but I think all of us with much experience have seen approaches that
were more about removal of an irritant or an undesired expense or simply
avoiding work rather than addressing the problem.  
    My experience to date is that producing errata and handling defect
reports is one of those places that is certainly an intrusive irritant and
also something where mitigating the risk of further error or even
degradation requires a painfully high level of care.  I find it remarkably
similar to software maintenance, and specifications of standards are, to me,
much more like code than literary narrative (and readability and
understandability is a high requirement for both code and standards
documents). 
    I suppose there is a lesson here about specification maintainability
that parallels the same experience with computer hardware (when it was
maintained at a rather fine level) and certainly with computer software.

 
-----Original Message-----
From: sc34wg6-bounces at vse.cz [mailto:sc34wg6-bounces at vse.cz] On Behalf Of
robert_weir at us.ibm.com
http://mailman.vse.cz/pipermail/sc34wg6/2010-January/000007.html
Sent: Saturday, January 09, 2010 08:14
To: sc34wg6 at vse.cz
Subject: Re: [Fwd: New ODF errata document - page & line numbers]

Hi Svante,  From the OASIS perspective, the only requirement is that 
errata consist of a "set of proposed corrections...in the form of a list 
of changes".

So anything that clearly and unambiguously indicates what the change is 
should be fine.

IMHO, line numbers are problematic when dealing when you have changes to 
tables or images, since indicating a line number is not always easy there.

But if you reference merely the clause number, makes sure that you give 
enough context to make it unambiguous.  So if you say "insert 'foo' before 
'bar' in section 1.2.3", then be sure that 'foo' occurs only once in that 
section.

-Rob


sc34wg6-bounces at vse.cz wrote on 01/08/2010 06:38:31 PM:
http://mailman.vse.cz/pipermail/sc34wg6/2010-January/000006.html

> Subject: New ODF errata document - page & line numbers
> Date: Fri, 08 Jan 2010 16:47:17 +0100
> From: Svante Schubert <Svante.Schubert at Sun.COM>
> To: sc34wg6-request at vse.cz
> 
> Hi,
> 
> I took over the role as an editor of the next ODF errata document and
> would like to ask in my role of a WG6 participant if there is an urgent
> need for page & line numbers in the OASIS errata document as an
> additional reference aside of the section and paragraph reference.
[ ... ]