comments

First, great job, and I will be recommending that many of my co-workers read
it. Sections 1.1.3 and 5 are particularly useful for grounding future
discussions on a variety of topics. 

More specific comments, by section number:

1.1 "this document does not include conformance provisions for at least
these reasons:" If there are more than three, say what they are, otherwise
take out the hint that there may be more ("at least").

1.1.3 "some design choices, like the names of the <p> and <li> elements in
HTML..." People with a strong XML background know that "<p> and <li>" are
not elements, but delimiters showing the beginnings of elements, and that
the use of the pointy brackets here is a typographical convention. Still,
you're calling "<p>" and "<li>" elements, and they're not. If you're
interested in making this document clearer to people without a strong XML
background, many of whom confuse tags with elements, I recommend using a
monospaced font to identify "p" and "li" as element names instead of pointy
brackets.

1.2.1 If you globally replace "orthogonal" with "independent," this section
will be much clearer and easier to understand. "Orthogonal" is trendy
engineering jargon, and as such has no place in this document--that is, if
you want the document to be clearly understood by the widest possible
audience. I checked at least four dictionaries, and not one had any
definitions supporting the usage here. I suppose the idea of being at right
angles is a metaphor for the relationship between the specs, but instead of
using a metaphor that doesn't scale up (each of fifteen specs can be
independent of the other fourteen; can each of fifteen lines be at right
angles to the other fourteen?) just say what you really mean to make the
document clearer.

3.4.1 A short example would help both bulleted items. 

4.5.6, number 3: "might reveal the attributes of type ID" means "might
reveal the attributes declared to be of type ID", right?

5 "Secondary resource" The definition for this doesn't make much sense out
of the context of section 2.6, and could use revision.

I only marked simple typos in the first few pages of my copy, but since some
were mentioned on the mailing list, I've noted them here:

1.1.1 "technologies and specifications in W3C" ("in the W3C")

1.2 "principles apply to across all three bases" delete "to" or "across"

1.2.2 "Context has determined which term" should read "Context determines
which term" for agreement of tense with sentence that precedes this ones.

1.2.3 "error condition so that a an agent" "so that an agent" 

Again, great work. 

Bob DuCharme          www.snee.com/bob           <bob@  
snee.com>  "The elements be kind to thee, and make thy
spirits all of comfort!" Anthony and Cleopatra, III ii

Received on Monday, 29 December 2003 13:00:16 UTC