Subject: Clarifying text and spec completeness

From: Ted Hardie <[email-masked]>
Date: Fri, 28 Jan 2005 11:07:18 -0800

Having followed the conversation over the past few days, I'm hearing
a lot of assertions over where the right place is to include clarifying
text and how much text is appropriate in various contexts.  Some of
those statements seem to have a lot of personal belief and heat
tied up in them, to the extent that I am concerned that they do not
reflect appropriate collegial treatment of other's opinions.  Please
be careful to respect each other, even when you disagree.

As a bit of AD guidance, let me tell the group that the IESG has in my term
rarely asked for the removal explanatory or clarifying text and has
quite often asked for an increase in such text.  This is a reflection
of the increased complexity of some of our standards and the
likelihood that those implementing a follow-on standard will not
have been those that implemented the original.

As a concrete example with bearing on these discussions, while the text
related to e-tag handling in the XCAP specifications might, in 
theory, be entirely
derived from other aspects of that spec or the underlying 
technologies, I and others
felt that it would be valuable to make the behavior explicit in the XCAP specs.
This was done with explanatory text and appropriate references to the
underlying specifications.  Making it overt also makes it far easier, to put it
bluntly, for us to tell if the spec gets it wrong.  That can be handy.

I certainly understand the desire not to bloat every specification to include
every other specification, and I respect the architectural purity of
full functional differentiation.  I encourage folks, though, to
to focus on the question:  "Will including this text increase or reduce the
likelihood of implementor producing an interoperable implementation?"
If there is a strong reason to believe the answer is "reduce", the text should
go.  If the answer is even likely to be "increase", though, erring on
the side of inclusion does no harm and might do good.

			regards,
				Ted Hardie

---

From: Julian Reschke <[email-masked]>
Date: Fri, 28 Jan 2005 21:20:25 +0100

Hi Ted,

in general I agree, but I'd like to add two points:

- Adding guidance or clarification can be dangerous, if it isn't done 
carefully. I speak from experience, having added two clarifications in 
the previous drafts that turned out to be simply incorrect (thanks to 
Geoff and Roy catching these).

- Many of the clarifications that people ask for have nothing to do with 
BIND, but with the base spec (RFC2518). Rather than discussing these 
things for BIND, I'd much prefer to get BIND out of the door, and then 
to invest our time into RFC2518bis (where those things really belong), 
which hasn't made a lot of progress in the last year.

Best regards,

Julian

-- 
<green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760

---

From: "Roy T. Fielding" <[email-masked]>
Date: Fri, 28 Jan 2005 17:22:00 -0800

> be careful to respect each other, even when you disagree.

Ted, while I agree with your advice, it is also inappropriate for
a working group chair to insist that their own comments take
priority over the opinion of the document authors and stated
opinions of the people reviewing the documents on the mailing list.
While such might be a reasonable position for a technical error or
security-related issue in the specification, it is not appropriate
for a matter of editorial preference.  When the IETF process is
ignored, discussion will inevitably begin to heat.

> have been those that implemented the original.

The IESG should not allow independent specifications to define the
behavior of other protocols, particularly when those other protocols
are at a higher level in the standards process.  They certainly did
not allow me to fix some of the bugs in MIME while I was defining HTTP.

> related to e-tag handling in the XCAP specifications might, in theory, 
> be entirely

Sorry Ted, but that is an excellent example. The XCAP specification
is so long that I hadn't bothered to read it, which is a pity
given that it is entirely dependent on two specifications for which
I did most of the authoring.  We should have learned that mistake
from RFC 2616.

I'll note, having just looked at draft-ietf-simple-xcap-05
Section 7.10, the description of etag makes it impossible for
XCAP documents to be managed by modern content management
applications (like those based on JSR 170) that are already
based on XML content trees.  In other words, your "valuable"
explicit behavior is both wrong and damaging to XCAP deployment
and should never have been placed in that spec.

I'll also point out that use of "/~~/" as "syntactic sugar"
is both unnecessary and a violation of basic URI design
principles.  Likewise, AUIDs are redundant to the information
already supplied by the media type and XML namespace.
Furthermore, use of Qnames as identifiers (Section 6.3)
outside of XML parsing is an architectural error unless
the document specification also guarantees that namespace
prefixes remain constant (the namespace prefix has no meaning
external to the parser tree and is therefore frequently
translated upon storage into a registered prefix name, which
may differ from the prefix used on PUT).  Finally, the grammar
for node-selector uses characters that are not allowed
by RFC 3986 to appear in any URI and the suggestion that they
be percent-encoded because of that is just laughable -- a
far more sensible idea would be to use a syntax that is
compatible with http URIs in the first place.

And, of course, it is so nice to know that XCAP is restricted
to HTTP/1.1, since that ties it to a specific version of a specific
transfer protocol and we all know that will never change, right?

Garbage.  The same protocol could have been defined by a
generic mapping of any application/*+xml document to path
segments in URI syntax; 5 pages max and independent of any
specific transfer protocol or XML Schema.

The whole point of splitting orthogonal protocols into orthogonal
specifications is to reduce complexity and coupling -- so that the
technologies can be defined and evolved independently.  XCAP fails
that miserably and will be a nightmare to maintain over time.

Cheers,

Roy T. Fielding                            <http://roy.gbiv.com/>
Chief Scientist, Day Software              <http://www.day.com/>

---

From: Ted Hardie <[email-masked]>
Date: Fri, 28 Jan 2005 17:51:08 -0800

Roy,
	Some responses inline.

>ignored, discussion will inevitably begin to heat.

One of the charges the IETF gives to a working group is to
ensure that the work meets the charter.  If the working group
chair or chairs believe it doesn't meet the charter (an implementable,
interoperable spec covering subject $FOO being a common
charge), it is her/his/their job to push.  Getting pushed back
is a part of the job too.  Failing to be collegial in one's behavior
during all of this pushing is not one of options.

So, everyone, please push carefully.

>not allow me to fix some of the bugs in MIME while I was defining HTTP.

This is absolutely correct.  But having a spec point to or excerpt
those specs to get guidance in front of the implementors does not
define those protocols, it highlights relevant issues.  That's not
a redefinition.

>and should never have been placed in that spec.

We should have this discussion on the SIMPLE mailing list, where
specific behavior for e-Tags was discussed extensively.  I believe
that the behavior they have specified is a restricted profile of
the permitted behaviors for e-Tags; that, at least, is the intent.
If you can demonstrate that the behavior they have specified
is *not permitted* by the base spec, then please say so to the
authors/IESG now.  The document is not yet out in the wild.

That said, I also believe we have to take specs and look at their
applicability as we evaluate them; some aspects of the work
of the IETF is to build building blocks of very general applicability
and some is to build protocols with narrow ranges of application.
XCAP was created for a very specific set of deployments, and in those
deployments the behavior specified not only makes sense, the WG
saw it as pretty close to optimal.  What scare me is the presumption
that XCAP will be generalizable, and that people will believe it is
a more general content management system.  The same choices
that made sense for managing a buddy list for a cell phone client
are lousy for managing a full-fledged XML data store.  But that doesn't
make the first one a task we shouldn't take on.

			regards,
				Ted Hardie