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

From: Robert Sparks <[email-masked]>
Date: Fri, 17 Jun 2011 15:37:20 -0500

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.

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

---

From: "Richard L. Barnes" <[email-masked]>
Date: Fri, 17 Jun 2011 17:10:13 -0400

> 5239 is maintainable going forward.

This seems sensible.  This document doesn't need to re-describe what's in RFC 4575 already, just the extension elements.  It would probably be good, though, to add a note to the first paragraph of S4.2 to say something like
"
The XCON data model re-uses the following child elements from RFC 4575:
  o <display-text>
  o <subject>
  o <free-text>
  o ...
"

--Richard