From owner-incits-v1@incits-v1.org Thu Jun 21 12:53:14 2007 Date: Thu, 21 Jun 2007 12:52:27 -0700 (PDT) From: jon.bosak@sun.com Subject: Re: INCITS-V1: NoteExampleConfusion-Durusau-3 In-reply-to: <026e01c7b2a3$ed168d40$c743a7c0$@com> Sender: owner-incits-v1@incits-v1.org To: incits-v1@incits-v1.org Reply-to: incits-v1@incits-v1.org X-PMX-Version: 5.2.0.264296 X-Authentication-warning: jurassic-x4600.sfbay.sun.com: bosak set sender to jon.bosak@sun.com using -f [Rex Jaeschke:] | I think the real question to consider regarding this comment is, | | "What is the material impact of not making such a change?" No, the real question to consider is, "what is the level of editorial quality expected in the Standards published by ANSI and JTC1?" In this committee, the answer to that question has always been, "very high." In judging whether an editorial failure should be corrected, we do not use as a criterion whether the fault causes material harm; we just correct it. | In any event, examples and notes are informative. As such, they | are intended to provide expository material that is useful, but | not necessary, for conformant implementation of the standard. I cannot recall ever having seen editorial problems uncovered in the review of informative materials defended on the grounds that the materials are informative. The distinction between normative and informative sections of a specification relates to expectations placed on conformant applications; it is not intended to distinguish portions written well from portions written badly. | If the contents of a specific example might better be described as | a note, or vice versa, a comment along those lines might be | appropriate. However, saying that "there are many of these" | without citing the instances specifically, or citing a pattern, | seems to me unlikely to result in the supposedly desired outcome, | especially if no justification is given for the request. (I | certainly don't buy the claim that readers will be confused.) The fact that some readers will be confused is amply proven by the fact that an expert reader found the distinction confusing. We can't be expected to enumerate every instance of this confusion among more than 5,000 "examples" and more than 600 "notes" in Part 4 alone; this is an unavoidable consequence of the decision to put a 6,000-page specification into a fast-track process. I'm not sure where the resistance to producing a high quality specification is coming from here. The installed base of Microsoft legacy documents guarantees that OOXML is something we're all going to have to live with for a long time, so we'd better get it right. Comments already adopted are going to require editorial changes before DIS 29500 can become an ISO/IEC standard in any case. Since we're going to have to go in under the hood anyway, we might as well do a proper job of it. The process of disambiguating comments from examples promises to be a tedious one, as I said before, but I expect that resources can be found for it. And it will provide a useful occasion for reviewing the code examples for redundancy as well. Jon