Subject: RE: LC on draft-mankin-pub-req-08.txt

From: "Stephen Hayes (TX/EUS)" <[email-masked]>
Date: Thu, 25 May 2006 07:18:47 -0500

See inline.

Stephen Hayes

> -----Original Message-----
> From: Joel M. Halpern [mailto:[email-masked]]
> Sent: Wednesday, May 24, 2006 3:17 PM
> To: [email-masked]
> 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."
>

Although the wording could be tuned to be more permissive, it's not possible to satisfy everybody with the POSTEDIT requirements.  People just tend to end up at slightly different places along the "how much the technical publisher should do" curve.  People can point to examples with badly written documents that needed considerable clean-up or examples where changes were done that added little overall benefit to a document.

The natural tendency of a technical publisher will be to improve documents, since to a large degree they view themselves as responsible for the output quality.  The current highly restrictive wording was selected to counterbalance that tendency.  The current wording also reflects that I heard more complaints about too much editing than not enough editing.

> 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."
> 
I agree, the requirements to keep metrics and the recommended values for metrics are different and should be distinguished in some way.  I am not sure an appendix is the best way, but some separation is needed.
> 
> 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.

I guess some minor surgery would be to change WGLC->WG, IETF LC-> IETF, and Formal Reviewing-> Reviewing.
> 
> Yours,
> Joel M. Halpern
> 
> 
> _______________________________________________
> Ietf mailing list
> [email-masked]
> https://www1.ietf.org/mailman/listinfo/ietf
> 

_______________________________________________
Ietf mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf

---

From: John C Klensin <[email-masked]>
Date: Thu, 25 May 2006 10:51:12 -0400

--On Thursday, 25 May, 2006 07:18 -0500 "Stephen Hayes (TX/EUS)"
<[email-masked]> wrote:

>...
> Although the wording could be tuned to be more permissive,
> it's not possible to satisfy everybody with the POSTEDIT
> requirements.  People just tend to end up at slightly
> different places along the "how much the technical publisher
> should do" curve.  People can point to examples with badly
> written documents that needed considerable clean-up or
> examples where changes were done that added little overall
> benefit to a document.
> 
> The natural tendency of a technical publisher will be to
> improve documents, since to a large degree they view
> themselves as responsible for the output quality.  The current
> highly restrictive wording was selected to counterbalance that
> tendency.  The current wording also reflects that I heard more
> complaints about too much editing than not enough editing.

Stephen, I routinely complain about too much editing -- if not
on every document I submit for RFC publication, at least most of
them.   I believe that, in the last couple of years there has
been a trend toward more editing that I consider gratuitous,
e.g., changing one correct and consistent style to another one.
So I may well be the source of some of the complaints you heard.
On the other hand, I'm appalled by the editorial and
presentation quality of some of the documents that I've seen go
to the RFC Editor, even after Last Call and IESG signoff.  

In my opinion, absent something that the document skirts, the
"current highly restrictive reading" goes much too far.  Yes, I
understand the desire to counterbalance both natural tendencies
and some history of over-editing.  But, to the extent to which
this document is expected, post-last-call, to form part of the
basis for solicitation of people who are interested in doing the
job and selection from among those people, and then of a
contract with the selected party, I believe it goes _much_ too
far: that degree of restrictiveness is simply not what we want
or need, IMO.

The exception case mentioned above would involve a shift to
doing substantially all editing prior to IETF Last Call and
doing it again if textual changes are made after Last Call, so
that the document that is approved is the document that is
published.  That is more or less the practice in a number of
other standards bodies.  For reasons of both cost and process,
it has never been embraced here and I don't take anything in
TechSpec as either forcing that model or as otherwise assuring
that documents that come into the process are of a quality that
would justify very restrictive text about post-editing.

regards,
     john