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." 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 Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
See inline. Stephen Hayes > -Original Message- > From: Joel M. Halpern [mailto:[EMAIL PROTECTED] > Sent: Wednesday, May 24, 2006 3:17 PM > To: ietf@ietf.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." > 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 > Ietf@ietf.org > https://www1.ietf.org/mailman/listinfo/ietf > ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
--On Thursday, 25 May, 2006 07:18 -0500 "Stephen Hayes (TX/EUS)" <[EMAIL PROTECTED]> wrote: > See inline. > > Stephen Hayes > >> -Original Message- >> From: Joel M. Halpern [mailto:[EMAIL PROTECTED] >> Sent: Wednesday, May 24, 2006 3:17 PM >> To: ietf@ietf.org >> Subject: Re: LC on draft-mankin-pub-req-08.txt >... > 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 ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
John Klensin wrote: > 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. Do you have any suggested text? What I am hearing is something like be frugal in changes except when the document needs it, which IMHO doesn't seem to help. Stephen ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
After some consideration, I can understand how the current text in mankin-pub-req would be discouraging to the technical publisher. If we changed "refrain from" to "exercise restraint in making" in requirements POSTEDIT-3 and POSTEDIT-4, I assume this would solve Joel and John's concerns. The question now is if I will get shot from the "keep your grubby hands off my document" crowd. Stephen > -Original Message- > From: Stephen Hayes (TX/EUS) [mailto:[EMAIL PROTECTED] > Sent: Thursday, May 25, 2006 8:01 PM > To: John C Klensin > Cc: Joel M. Halpern; ietf@ietf.org > Subject: RE: LC on draft-mankin-pub-req-08.txt > > > John Klensin wrote: > > 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. > > Do you have any suggested text? What I am hearing is > something like be frugal in changes except when the document > needs it, which IMHO doesn't seem to help. > > Stephen > > ___ > Ietf mailing list > Ietf@ietf.org > https://www1.ietf.org/mailman/listinfo/ietf > ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
--On Thursday, 25 May, 2006 20:27 -0500 "Stephen Hayes (TX/EUS)" <[EMAIL PROTECTED]> wrote: > After some consideration, I can understand how the current > text in mankin-pub-req would be discouraging to the technical > publisher. > > If we changed "refrain from" to "exercise restraint in making" > in requirements POSTEDIT-3 and POSTEDIT-4, I assume this would > solve Joel and John's concerns. Yes, from my standpoint, that would be a very significant improvement. > The question now is if I will get shot from the "keep your > grubby hands off my document" crowd. One hopes not. But that question is, of course, intimately related to whether there is actually a plausible pre-approval editing process (not just a suggestion process to editors, but actual definitive editing). If there is no such process, then, for some very significant number of cases "keep your hands off my document" would be equivalent to "publish ungrammatical, badly-written and badly-organized trash". And I don't think anyone really wants that. john ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
I can live with that. And I hope so can those who want to be restrictive as to what editing takes place. Yours, Joel At 09:27 PM 5/25/2006, Stephen Hayes (TX/EUS) wrote: After some consideration, I can understand how the current text in mankin-pub-req would be discouraging to the technical publisher. If we changed "refrain from" to "exercise restraint in making" in requirements POSTEDIT-3 and POSTEDIT-4, I assume this would solve Joel and John's concerns. The question now is if I will get shot from the "keep your grubby hands off my document" crowd. Stephen ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
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." 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 Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
Joel, Please see my comments below... -- Eric --> -Original Message- --> From: Joel M. Halpern [mailto:[EMAIL PROTECTED] --> Sent: Wednesday, May 24, 2006 4:11 PM --> To: ietf@ietf.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. --> 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 --> Ietf@ietf.org --> https://www1.ietf.org/mailman/listinfo/ietf --> ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
*> *>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 ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
Bob, Weirdness? No part of the RFC Editor's "job" has ever involved deliberate modification of text that reflects a carefully crafted compromise position. In the past, when any such modification has occurred inadvertently, it would usually have been reversed during an Auth48. I believe what we're trying to do is define what the RFC Editor does already in terms that might allow us to off-load part of that task. So, NO I am not saying "Don't do your job most of the time" - what I am saying is that "restraint should be used in this task to avoid doing more than the task requires." To make this something we can look at more objectively, let's look at a different example of the same usage. Surely, you would agree that a statement such as - "People should refrain from allowing their passion for precise terminology usage to prevent essential communication from ever taking place" - is a far cry from - "Nit-picking is prohibited." -- Eric --> -Original Message- --> From: Bob Braden [mailto:[EMAIL PROTECTED] --> Sent: Thursday, June 01, 2006 5:17 PM --> To: [EMAIL PROTECTED]; [EMAIL PROTECTED] --> Cc: ietf@ietf.org --> Subject: RE: LC on draft-mankin-pub-req-08.txt --> --> --> --> *> --> *>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 --> ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
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 ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
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 PROTECTED] --> Sent: Thursday, June 01, 2006 6:43 PM --> To: [EMAIL PROTECTED]; [EMAIL PROTECTED] --> Cc: [EMAIL PROTECTED]; ietf@ietf.org --> 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 --> ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
On Thu, 1 Jun 2006, Gray, Eric wrote: Bob, Weirdness? No part of the RFC Editor's "job" has ever involved deliberate modification of text that reflects a carefully crafted compromise position. In the past, when any such modification has occurred inadvertently, it would usually have been reversed during an Auth48. I believe what we're trying to do is define what the RFC Editor does already in terms that might allow us to off-load part of that task. So, NO I am not saying "Don't do your job most of the time" - what I am saying is that "restraint should be used in this task to avoid doing more than the task requires." To make this something we can look at more objectively, let's look at a different example of the same usage. Surely, you would agree that a statement such as - "People should refrain from allowing their passion for precise terminology usage to prevent essential communication from ever taking place" Eric - I think your vision of what at editor does may be a bit limited here. You seem to be describing the zone between proofreading and copy editing (correcting grammar, conforming to accepted style, reference checking, etc.) but you're missing a much more important piece - comprehensive editing. In the IETF case a document may begin with language crafting at the WG level, move through last call, gen-art reviews, and the IESG and still need major fine tuning for basic readability. I'll agree with you that editorial changes to a text should be made with an eye to intent of the authors with regard to the *technical* content but the back-and-forth of final editorial review should catch any substantive changes in the authors intent. We sometimes do a good job at the layer of technical/peer review, however, I've seen far to many documents that may be technically sound but are poorly structured and poorly written. In addition, drafts are often pitched to a reader already well up to speed with internal terms so that the word choices are loaded in ways that make the document unreadable to outsiders. Abstracts and definitions of terms are often sketchy at best. Pressure is applied at every level inside the IETF to advance any given document and we NEED the combination of comprehensive editing, copy editing, and proofreading at the RFC-Editor level in order to produce a readable and reliable document series. I'm with Joel here, I *want* our documents to be well written and I believe that improving the readability of a document is a major part of what we currently expect from our RFC-Editor process. - Lucy - is a far cry from - "Nit-picking is prohibited." -- Eric --> -Original Message- --> From: Bob Braden [mailto:[EMAIL PROTECTED] --> Sent: Thursday, June 01, 2006 5:17 PM --> To: [EMAIL PROTECTED]; [EMAIL PROTECTED] --> Cc: ietf@ietf.org --> Subject: RE: LC on draft-mankin-pub-req-08.txt --> --> --> --> *> --> *> 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 --> ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf -- Lucy E. Lynch Academic User Services Computing CenterUniversity of Oregon llynch @darkwing.uoregon.edu (541) 346-1774 ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: LC on draft-mankin-pub-req-08.txt
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 PROTECTED] > Sent: Wednesday, May 24, 2006 3:11 PM > To: ietf@ietf.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@ietf.org > https://www1.ietf.org/mailman/listinfo/ietf > ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
