This posting was somehow delayed, but still seemed to generate some comments.
See proposed resolutions inline.
Stephen Hayes
-----Original Message-----
From: Joel M. Halpern [mailto:jmh(_at_)joelhalpern(_dot_)com]
Sent: Wednesday, May 24, 2006 3:11 PM
To: ietf(_at_)ietf(_dot_)org
Subject: Re: LC on draft-mankin-pub-req-08.txt
Reading this, a few items caught my eye.
The POSTEDIT requirements seem to be worded as if it is desirable to
minimize the changes that the document editor makes, or even the
changes the document editor can make. The general tone of "don't
mess with the words we have carefully honed" is
understandable. However, in practice many of the words have not been
carefully honed. And they need to be. For example, there is a
document I just reviewed to which my personal reaction is "this needs
massive editing." It is not technically wrong. But the language use
makes it hard for the reader to understand what is intended. I would
sincerely hope that if it is approved as-is by the IESG that the RFC
Editor would edit the document.
In general the editor has little or no way to tell which words are
"carefully crafted." I would hate to have a presumption that all the
words a sacrosanct.
I realize that the text calls out the special case of "don't touch a
letter of this", and even acknowledges that it is a rare case. But
the wording of the earlier text is not in line with
that. Specifically, POSTEDIT-4 reads "The IETF Technical editor
should refrain from changes to improve readability that may change
technical and consensus wording." This appears to be a directive
that prohibits almost all changes, since in a formal sense all the
words in an WG and IETF LC approved document are "consensus
wording." That leads to what I consider a bad situation where we
have essentially prohibited the editor from editing.
On a related note, POSTEDIT-3 seems to be inadvertently worded too
strongly. It prohibits changes which "introduce a substantial review
load but only provides incremental increase in the clarity of the
specification." However, by definition any change at all, even a
significant change that transforms a document from unintelligible to
highly readable, is always an "incremental increase in the clarity of
the specification."
With regard to the metrics, I think that it would be helpful to
separate the notion of having metrics from the specific values. I
would suggest moving the specific values to an appendix, with a
notation that these values are advisory and based on IETF perception
at the time of writing. I don't want to lose the numbers, but I
think that they have a different status as requirements than the
point that these time frames should be tracked, and should have well
understood targets. Separating this also allows for negotiation of
cost-benefit tradeoffs without violating "requirements."
The proposed compromise is to change "refrain from" to "exercise restraint in
making" in requirements POSTEDIT-3 and POSTEDIT-4. Making everybody 100% happy
with this text is impossible because we are talking about shades of grey.
Nobody wants poorly written documents and nobody wants the editor changing the
semantics of a document. However, based on the comments I have received, I
believe that the bulk of the IETF community would prefer to err on the side of
maintaining the author's semantics.
Still I hope the proposed text of exercising restraint in making changes is
acceptable. I think it respects the professionalism of the publisher while at
the same time communicating the risks of improving readability.
As a minor matter, figure one is trying to make a useful statement,
but one of the headings caused me to have to spend more time staring
at the figure, rather than making things clearer. In the row labeled
"Actors", WGLC and IETF LC appear. Those are states, not
actors. Also, the action listed (Formal Reviewing) does not, as far
as I know, currently occur during those phases. The formal reviewing
occurs after IETF LC ends, during IESG deliberations.
Propose to change WGLC->WG, IETF LC-> IETF, and Formal Reviewing-> Reviewing.
Yours,
Joel M. Halpern
_______________________________________________
Ietf mailing list
Ietf(_at_)ietf(_dot_)org
https://www1.ietf.org/mailman/listinfo/ietf
_______________________________________________
Ietf mailing list
Ietf(_at_)ietf(_dot_)org
https://www1.ietf.org/mailman/listinfo/ietf