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

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 24 May 2006 16:10:35 -0400

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

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.

Yours,
Joel M. Halpern

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

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 24 May 2006 16:10:35 -0400

Yours,
Joel M. Halpern

---

From: "Gray, Eric" <[email-masked]>
Date: Thu, 1 Jun 2006 17:06:02 -0400

Joel,

	Please see my comments below...

--
Eric 

--> -----Original Message-----
--> From: Joel M. Halpern [mailto:[email-masked]] 
--> Sent: Wednesday, May 24, 2006 4:11 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.
-->

	I believe that people are leaning in the direction of
requiring authors to do a better job before gaining approval
required to put the remainder of the job on the RFC Editor's
desk.

	As worded now, it seems as if the cases to which higher
numbered requirements (in the series under discussion - i.e.
- requirements Req-POSTEDIT-3, 4 and 5) have progressively (or
incrementally) greater restrictions on their applicability to
documents generally.  I think this is as it should be and it
may well be the case that future IESG approvals may include a
note as to which levels of editing may be applied to a given
draft 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 am reasonably sure that this is not as difficult as 
it sounds.  For one thing, if the current draft revision is
-23, we can be reasonably sure that tweaking anything that 
is not clearly a typo or spelling error will be a case of 
modifying "carefully crafted" wording.

	On the other hand, modifying wording of a revision -02
(or lower) document that is laced with typos, spelling and 
grammatical errors from end to end (the "massive editing" 
example you gave) is unlikely to fall in the same category.

	I believe we can expect a technical editor to use their
own judgement between these two extremes - at least in most
cases.

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

	Bearing in mind that asking someone to "refrain from" 
doing something is a far cry from "prohibiting" it, see my 
comment above.

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

	Here I must confess to some sympathy.  Like me, you 
probably cringe when you here the phrase "more granular"
because this usage is just wrong.  However, in this case,
one of the established definitions of "incremental" is:

      "A slight, often barely perceptible augmentation."

	It might be better to choose a less ambiguous word,
but I believe the meaning is clear.

--> 
--> With regard to the metrics, [...]

--- [SNIP] ---

	I agree with your other observations and suggestions.

--> 
--> Yours,
--> Joel M. Halpern
--> 
--> 
--> _______________________________________________
--> Ietf mailing list
--> [email-masked]
--> https://www1.ietf.org/mailman/listinfo/ietf
-->

---

From: Bob Braden <[email-masked]>
Date: Thu, 1 Jun 2006 14:17:21 -0700 (PDT)

*> 
  *> 	Bearing in mind that asking someone to "refrain from" 
  *> doing something is a far cry from "prohibiting" it, see my 
  *> comment above.
  *> 

Sorry, I don't get that fine distinction.  Are you saying, "Don't
do your job most of the time"?  Wierdness abounds here.

Bob Braden

---

From: Bob Braden <[email-masked]>
Date: Thu, 1 Jun 2006 15:42:32 -0700 (PDT)

*> 
  *> "People should refrain from allowing their passion for precise
  *>  terminology usage to prevent essential communication from 
  *>  ever taking place"
  *> 

That statement incorporates an assumption that is not true.  I vaguely
recall that you can prove anything starting from a false premise.

Bob Braden

  *> - is a far cry from -
  *> 
  *> "Nit-picking is prohibited."

Your choice of the emotion-packed word "nit-picking" reveals that you and
I cannot have a sensible discussion.  Is a bug in a programs a nit? Is
bad English grammar a nit?  Is ambiguous prose or terminology a nit?

Bob Braden

---

From: "Gray, Eric" <[email-masked]>
Date: Thu, 1 Jun 2006 20:00:00 -0400

Bob,

	To me, this is a perfectly sensible discussion, and my
analogy was perfectly reasonable.

	Joel suggested that refraining from making changes that
might result in altering phraseology that was carefully arrived
at was effectively prohibiting the technical editor from doing
the editing job.  I say that the editing job can be done - as
it is being done now - within the bounds of this constraint.

	I think this makes a lot of sense.  The Editor makes it
very clear what his/her specific requirements and standards of
acceptability are and these are certainly taken into account
in the process of word-smithing key phraseology - in many cases
if not necessarily all (especially by the time IESG approval 
occurs).  At the same time, the people writing a specification 
would not normally like to feel that the Editor must be a party 
to word-smithing of this same key phraseology - except from the 
stand-point of readability and clarity within the context of the 
purpose of the document.

	The concern I see being expressed in the draft is that we
want to ensure that the current practice of reasoned prudence
in making editorial changes is continued.  This is a perfectly
valid concern.

	As for emotional charge in the term "nit-picking" - I see
none.  As anyone who knows me can assure you, I am the last one
in the world who will throw stones in that glass house.  Since
the term derives from the practice of de-lousing, I can hardly
imagine it to be necessarily a bad thing.

	Finally, ambiguity is sometimes precisely what has been
negotiated into a specification and this should be legitimate
if the effect of the ambiguity is irrelevant to the purpose of
the document.  An instance of this is an example, provided not
to instruct but to illustrate functionality in the abstract.

--
Eric	

--> -----Original Message-----
--> From: Bob Braden [mailto:[email-masked]] 
--> Sent: Thursday, June 01, 2006 6:43 PM
--> To: [email-masked]; [email-masked]
--> Cc: [email-masked]; [email-masked]
--> Subject: RE: LC on draft-mankin-pub-req-08.txt
--> 
--> 
-->   *> 
-->   *> "People should refrain from allowing their passion for precise
-->   *>  terminology usage to prevent essential communication from 
-->   *>  ever taking place"
-->   *> 
--> 
--> That statement incorporates an assumption that is not true. 
-->  I vaguely
--> recall that you can prove anything starting from a false premise.
--> 
--> Bob Braden
--> 
-->   *> - is a far cry from -
-->   *> 
-->   *> "Nit-picking is prohibited."
--> 
--> Your choice of the emotion-packed word "nit-picking" 
--> reveals that you and
--> I cannot have a sensible discussion.  Is a bug in a 
--> programs a nit? Is
--> bad English grammar a nit?  Is ambiguous prose or terminology a nit?
--> 
--> Bob Braden
-->

---

From: "Stephen Hayes (TX/EUS)" <[email-masked]>
Date: Sat, 3 Jun 2006 16:13:13 -0500

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:[email-masked]]
> Sent: Wednesday, May 24, 2006 3:11 PM
> To: [email-masked]
> Subject: Re: LC on draft-mankin-pub-req-08.txt
> 
> 
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.

> occurs after IETF LC ends, during IESG deliberations.

Propose to change WGLC->WG, IETF LC-> IETF, and Formal Reviewing-> Reviewing.