Subject: RE: [Simple] Double specification: text and schema

From: "Mary Barnes" <[email-masked]>
Date: Fri, 2 Jul 2004 10:02:09 -0400

I agree with Joel; I think we're getting back to the fundamental debate on
whether one should comment code or whether good code is self documenting (or
whether detailed design documents should have pseudo-code or real code,
etc.)  It is important to have good and accurate as possible textual
descriptions along with the XML. And, I don't see a problem with it being
normative, either (in fact that would be my preference). I don't consider
myself an XML guru, but I can manage my way through with the appropriate
normative text.  That's how it's done for all the other specs; why should
the XML based specs be any different?    

Certainly, there are issues with some of the current documents in the text
that could be further clarified to ensure consistency with the XML schema,
but I think that's along the lines of the last point you make below about
putting a "bit of effort" in writing the documents.    

Regards,
Mary.

-----Original Message-----
From: Miguel Garcia [mailto:[email-masked]] 
Sent: Friday, July 02, 2004 8:16 AM
To: Joel M. Halpern
Cc: Jonathan Rosenberg; SIMPLE mailing list
Subject: Re: [Simple] Double specification: text and schema

Well, here is the disagreement. I just want to tell authors: "don't use 
normative text when there is normative definition expressed in the schema".

Believe me, and record my words for a future time: if we start doing 
double specification of normative requirements in RFCs, we will face 
interoperability problems.

If you are not able to put a bit of effort when writing your documents, 
we all will pay in the future.

- Miguel

Joel M. Halpern wrote:

> Part of what I am trying to avoid is telling authors that they must be 
> extra careful never to use MUST words about things described in the 
> schema.  In a typical text description there will be explanatory text, 
> there will be explanation of requirements that are also in the schema, 
> and there will be explanation of requirements that are not in the 
> schema.  (Occasionally one gets lucky and the last category is empty.)
> As an author, I really don't want to have to try to change style from 
> sentence to sentence in a section depending upon whether or not the 
> particular behavior I am describing also occurs in the schema.
> Also, as I reader I would like to see a complete description in the text.
> 
> Yours,
> Joel M. Halpern
> 
> At 06:23 AM 7/2/2004 -0400, Jonathan Rosenberg wrote:
> 
> 
>> Miguel Garcia wrote:
>>
>>> Hi Joel:
>>> I don't agree with you. We can't avoid the XML schema. I believe you 
>>> agree with me.
>>> Since the XML schema already needs to indicate whether an element or 
>>> attribute is mandatory or not, there is no point in repeating the 
>>> same information in the text. What for?
>>
>>
>> I think that it can be useful for purposes of clarification. I would 
>> advise using non-normative terminology in the text. So, for example:
>>
>> "The <foo> element includes a single mandatory attribute, "bar", and 
>> always has two children, <sip> and <ping>..."
>>
>> I think it also makes sense to have an explicit statement about the 
>> normative nature of the schema, and that any explanatory text is not 
>> normative. I routinely put such statements in "overview of operations" 
>> sections, which are not written with RFC2119-strentgh terms.
>>
>> -Jonathan R.
>>
>> -- 
>> Jonathan D. Rosenberg, Ph.D.                600 Lanidex Plaza
>> Chief Technology Officer                    Parsippany, NJ 07054-2711
>> dynamicsoft
>> [email-masked]                     FAX:   (973) 952-5050
>> http://www.jdrosen.net                      PHONE: (973) 952-5000
>> http://www.dynamicsoft.com
>>
>> _______________________________________________
>> Simple mailing list
>> [email-masked]
>> https://www1.ietf.org/mailman/listinfo/simple
> 
> 

-- 
Miguel A. Garcia           tel:+358-50-4804586
Nokia Research Center      Helsinki, Finland

_______________________________________________
Simple mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/simple
_______________________________________________
Simple mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/simple

---

From: Miguel Garcia <[email-masked]>
Date: Mon, 05 Jul 2004 09:47:06 +0300

Hi Mary:

I don't have any problem with having accurate comments on the text. My 
problem is with having normative statements that, at some point in time, 
may differ with the XML schema (which is also normative). I am just 
seeking for a future proof specification that allows interoperability.

I have seen many other SDOs that systematically repeat normative 
statements across the same or different specifications, and you know 
what? They are always divergencies. As I want to avoid this divergence, 
my proposal is to avoid normative statements when the normative part is 
described in the XML schema.

I still think that Jonathan's proposal was excellent: comment the XML 
schema in the text, but avoid normative statements.

- Miguel

Mary Barnes wrote:
> I agree with Joel; I think we're getting back to the fundamental debate 
> on whether one should comment code or whether good code is self 
> documenting (or whether detailed design documents should have 
> pseudo-code or real code, etc.)  It is important to have good and 
> accurate as possible textual descriptions along with the XML. And, I 
> don't see a problem with it being normative, either (in fact that would 
> be my preference). I don't consider myself an XML guru, but I can manage 
> my way through with the appropriate normative text.  That's how it's 
> done for all the other specs; why should the XML based specs be any 
> different?   
> 
> Certainly, there are issues with some of the current documents in the 
> text that could be further clarified to ensure consistency with the XML 
> schema, but I think that's along the lines of the last point you make 
> below about putting a "bit of effort" in writing the documents.   
> 
> Regards,
> Mary.
>