RE: Updated versioning strategies doc [XMLVersioning-41 ISSUE-41]

Comments inline and updates done to 
http://www.w3.org/2001/tag/doc/versioning-compatibility-strategies
http://www.w3.org/2001/tag/doc/versioning-compatibility-strategies-20071
026.html

Cheers,
Dave

> -----Original Message-----
> From: noah_mendelsohn@us.ibm.com [mailto:noah_mendelsohn@us.ibm.com] 
> Sent: Friday, November 02, 2007 4:55 PM
> To: David Orchard
> Cc: Dan Connolly; www-tag
> Subject: RE: Updated versioning strategies doc 
> [XMLVersioning-41 ISSUE-41]
> 
> I've gotten several pages in on my review, but not all the 
> way.  Given that we're meeting on Monday, I thought it would 
> be most useful to pass on the comments I have so far.  These 
> comments reflect a review of the text up to the start of 
> section "2.1.1 Identifying Languages".  Also, these are just 
> the main points I'd make.  I have some detailed editorial 
> suggestions and concerns that I'll try to post later.
> 
> * Mostly I agree with the main points that the draft seems to 
> be trying to make, and I think that's real progress.  Some 
> exceptions are noted below.

Excellent

> 
> * The introduction assumes too much knowledge of concepts and 
> terminology. 
>  For example, in the 2nd paragraph we find: "This finding 
> describes general problems and techniques in evolving systems 
> in compatible ways. A number of design patterns and rules are 
> discussed with a focus towards 
> enabling forwards-compatible changes to languages."   We 
> haven't said a 
> thing about what forwards compatible versioning is, and 
> indeed the draft 
> doesn't address that until several pages later.   Readers will think 
> "should I understand that?".  Better might be:  "This finding 
> describes general problems and techniques in evolving systems 
> in compatible ways. A number of design patterns and rules are 
> discussed, with a particular focus on enabling older versions 
> of applications to operate on inputs that make 
> use of newer language features."    The introduction is an 
> important part 
> of the document and it shouldn't be confusing to new readers. 
>   I think it 
> needs some significant rework to deal with issues like this, 
> but I mostly agree with what I think it's trying to see.
> 
> * There are many other unexplained forward references to 
> terminology that need to be fixed.  In addition to 
> "forwards-compatible" as mentioned above, I see unexplained 
> references to "extensible" (in the list of good practices in 
> section 1); "schema" (which is not always used in the usual 
> sense); "flavors of a schema"; "resources" (which appears to 
> be used for something that resembles a consuming application 
> rather than what Web Arch calls a resource  -- for example 
> there is a phrase "if a language is changed in such a way 
> that all those resources will consider texts of the new 
> language invalid"  -- I don't think Web Arch resources 
> typically implement the verb "consider"); "our Name example" 
> (the draft says "Recall our Name example and consider... ", 
> but in fact the Name example has been neither introduced nor 
> referenced); and "component" (in the name example). 
>   All this unexplained terminology seems to undercut the 
> rigor of the presentation, without making it particularly 
> easier to read or more accessible.  It's just confusing. 
> 

I've tried to go through and do the updtes you listed.  I wasn't sure
what to do about language should be extensible.  Link to the definition,
or come up with some other set of words such as "Language should allow
components beyond those defined by the language" but that lacks the
punchiness of "be extensible".  

> * Section 1: "if the texts of the language contain version 
> identifiers, then texts where the version identifier is 
> unknown can be treated as if the version identifier was 
> known."  This has a number of problems I think. 
>  First of all it presupposes that such identifiers are 
> optional.  One approach is to make them mandatory, in which 
> case you don't need to say what to do if they're missing, 
> other than to say the document is not legal.  Even if they 
> are optional, it's not at all clear that you need to treat 
> the document as if it were of some other version that could 
> have been specifically identified.  I think a better rule 
> would be something
> like:  "If a language allows for version identifiers in 
> document text, and if use of those identifiers is optional, 
> then the language must provide for the interpretation of 
> documents in which the version identifier is 
> absent."   I think that covers all the cases, and more accurately. 
> 

Actually, this is missing the point.  It's not about interpretation if
the id is missing, it's interpretation if the id received is unknown.
For example, what does an XML 1.0 processor do when it sees a document
identified as XML 1.1?   I stand by the statement in the text, that
forwards compatibility requires that unknown version identifiers can be
treated as known identifiers.

> * Section 1.2: "Just Names: some languages don't actually 
> have a syntax or grammar; they're just lists of names."  I 
> think we need to very carefully introduce the sense in which 
> we're using the words "syntax" and "grammar" 
> before saying this.  My understanding is that historically, 
> syntax has indeed referred to the structure of words in 
> sentences, etc., and you are right that a simple list of 
> words doesn't have syntax in that sense.  On the other hand, 
> one can find references in the computer field which seem to 
> suggest using syntax to refer to the legal forms of text 
> input for some system.  In that sense, languages that just 
> allow names, or lists of names have a syntax, albeit a simple 
> one.  The grammer is just the degenerate "a token" or "a 
> space separated list of tokens" (BTW: you should be clearer 
> as to whether you're talking about languages in which each 
> document contains a single name, but you get to choose it 
> from a list, or whether 
> you mean a language in which each instance is a list.   I 
> couldn't tell.) 
> For our purposes, I think I'd prefer to take the approach 
> that all languages have syntax, though for some lanuage the 
> structure of legal documents is simple to the point of being 
> trivial;  for such languages, the grammers are correspondingly simple.
> 

That is a good point.  How about "some languages are just list(s) of
acceptable names. " and avoid the use of syntax or grammar completely?
No need to introduce it here..

> I hope this is helpful. 
> 

Yes!
> Noah

Received on Tuesday, 6 November 2007 02:55:48 UTC