Re: Clarifying text and spec completeness

On Jan 28, 2005, at 11:07 AM, Ted Hardie wrote:

> 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.

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.

> 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.

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.

> 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.

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.


Roy T. Fielding                            <>
Chief Scientist, Day Software              <>

Received on Saturday, 29 January 2005 01:22:01 UTC