Clarifying text and spec completeness

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

Received on Friday, 28 January 2005 19:07:56 UTC