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

Ben Campbell <ben@estacado.net> Wed, 10 August 2011 01:02 UTC

Return-Path: <ben@estacado.net>
X-Original-To: xcon@ietfa.amsl.com
Delivered-To: xcon@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 8ADE021F84E4 for <xcon@ietfa.amsl.com>; Tue, 9 Aug 2011 18:02:19 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.499
X-Spam-Level:
X-Spam-Status: No, score=-2.499 tagged_above=-999 required=5 tests=[AWL=0.100, BAYES_00=-2.599]
Received: from mail.ietf.org ([12.22.58.30]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id IztpKwGVL4ty for <xcon@ietfa.amsl.com>; Tue, 9 Aug 2011 18:02:19 -0700 (PDT)
Received: from estacado.net (estacado-pt.tunnel.tserv2.fmt.ipv6.he.net [IPv6:2001:470:1f03:266::2]) by ietfa.amsl.com (Postfix) with ESMTP id A803E21F84E6 for <xcon@ietf.org>; Tue, 9 Aug 2011 18:02:18 -0700 (PDT)
Received: from [10.0.1.6] (cpe-76-187-75-59.tx.res.rr.com [76.187.75.59]) (authenticated bits=0) by estacado.net (8.14.3/8.14.3) with ESMTP id p7A12Ug0018611 (version=TLSv1/SSLv3 cipher=AES128-SHA bits=128 verify=NO); Tue, 9 Aug 2011 20:02:35 -0500 (CDT) (envelope-from ben@estacado.net)
Mime-Version: 1.0 (Apple Message framework v1244.3)
Content-Type: text/plain; charset=us-ascii
From: Ben Campbell <ben@estacado.net>
In-Reply-To: <642D74C0-A298-47E4-A0C2-3819D4E093BD@nostrum.com>
Date: Tue, 9 Aug 2011 20:02:30 -0500
Content-Transfer-Encoding: quoted-printable
Message-Id: <89DAF676-85CF-4043-863F-61B018104DBB@estacado.net>
References: <642D74C0-A298-47E4-A0C2-3819D4E093BD@nostrum.com>
To: Robert Sparks <rjsparks@nostrum.com>
X-Mailer: Apple Mail (2.1244.3)
Cc: pete resnick <presnick@qualcomm.com>, xcon@ietf.org, draft-ietf-xcon-common-data-model@tools.ietf.org
Subject: Re: [XCON] Should we keep or adjust some of the redundant text in common-data-model?
X-BeenThere: xcon@ietf.org
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: Centralized Conferencing <xcon.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/xcon>, <mailto:xcon-request@ietf.org?subject=unsubscribe>
List-Archive: <http://www.ietf.org/mail-archive/web/xcon>
List-Post: <mailto:xcon@ietf.org>
List-Help: <mailto:xcon-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/xcon>, <mailto:xcon-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 10 Aug 2011 01:02:19 -0000

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
> XCON@ietf.org
> https://www.ietf.org/mailman/listinfo/xcon