Re: [XCON] Should we keep or adjust some of the redundant text in common-data-model?

[Ben Campbell <[e-mail]>]

On Jun 17, 2011, at 3:37 PM, Robert Sparks wrote:

> All -
> 
> During IESG evaluation, Pete Resnick observed that common-data-model, ccmp, and the examples document
> each had places where the documents repeated each other, and repeated clauses from the documents they
> depend on (such as RFC4575) in ways that make the document harder to read and introduce the possibility
> of conflict between those documents, especially as they are maintained in the future.

It's been a while, but I think I had a similar concern doing the gen-art review, but decided not to comment on it as I thought it was more a question of style than substance. But I agree it is probably more readable and less maintenance error prone without the redundant sections.  

That being said, common-data-model defines an xml-schema. The question to me would be whether that schema is complete with the sections removed, keeping in mind that schemas including elements from other RFC can be precarious. But on a quick re-scan, and assuming the elements would stay in the Relax-NG definition, the sections in question seem descriptive only. 

Perhaps a single section that says "elements X,Y, and Z are as defined in [RFC4975]? I know the draft effectively does that in section 4, but following a bunch of asterisks in ascii art is a bit hard on the eyes.

> 
> Pete has a concrete suggestion for removing the redundancy in this document in his DISCUSS at
> <https://datatracker.ietf.org/doc/draft-ietf-xcon-common-data-model/ballot/>. I would like to confirm that
> people have considered the potential for conflict between the documents in the future and want to maintain
> the text as it is currently constructed anyhow, or if the changes Pete proposes are acceptable to the group.
> Either answer is ok - the point of Pete's DISCUSS is to confirm that the working group has considered this
> possibility rather than to insist on a particular change.
> 
> Pete's proposal is to completely remove sections like 4.2.2 and 4.2.3 which currently say
>> 4.2.2.  <display-text>
>> 
>>   The <display-text> element is described in section 5.3 of [RFC4575].
>> 
>> 4.2.3.  <subject>
>> 
>>   The <subject> element is described in section 5.3 of [RFC4575].
> to remove similar sections that copy sentences forward from 4575, like
>> 4.2.11.  <service-uris>
>> 
>>   The <service-uris> describes auxiliary services available for the
>>   conference.  The <service-uris> element is described in section 5.3.2
>>   of [RFC4575].
> (note that that first sentence is also the first sentence of 5.3.2 in 4575),
> 
> to avoid things that could be interpreted as clarifications or even updates to 4575, such as the
> first sentence of 4.2.10:
>> 4.2.10.  <conf-uris>
>> 
>>   The <conf-uris> element contains the identifiers to be used in order
>>   to access the conference by different signaling means. 
> 
> and to avoid duplication and some of the coupling with other documents
> throughout the introduction, by removing paragraphs 2, 3, and 4, and the figure.
> 
> Please see the link to the discuss text for the full set of proposed changes.
> 
> What does the group think?
> 
> My 2cents - I agree with the principle behind Pete's suggestion, and I think my first read of the document would have
> been smoother without sections like 4.2.2. I think the opportunity for error introduced by drift as the
> documents are maintained is very low, but the editorial effort to avoid that risk is also very low.
> I am less convinced that the introductory material is redundant and think the coupling with, for instance,
> 5239 is maintainable going forward.
> 
> RjS
> 
> 
> _______________________________________________
> XCON mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/xcon