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
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
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
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: comments on
Craig Partride wrote: > I don't think the IAB and IRSG are part of the IETF > family. If they > are part of a family, it would be ISOC. So I'd just say > "This draft > only addresses IETF documents processed by the IESG." > The intention was that these requirements would apply when processing documents that come from the IETF (via the IESG), the IRSG, or the IAB. We can perhaps find a different name for the group of entities, but the idea was to have consistent publication requirements between the organizations. IESG processed documents is too restrictive. > Another problem spot was 4.1, post-approval timeframes. I have two > concerns: > > * One month turnaround is a swift requirement in any > publishing system. > I suspect it is unreasonable. Before starting the requirements I checked with several other standards organizations on what their publication policies are. An under one month average is quite achievable. Many of the other organizations have tighter deadlines and much burstier load. It is realized that there is a tradeoff between speed and cost. The contractual targets have to be contractually decided. This is intended to represent what the IETF community feels is desirable. > > * The metric has no discussion of document length. There's a big > difference between a 20 page document and a 100 page > document and > it affects turnaround times. The one-month average is a statistical measure. It is realized some documents will take longer. It is expected that some documents would be processed faster. > > * There's no discussion of arrival process -- my bet is > that things > come in pulses. Again, that's a workload issue we need to be > aware of. If work comes in pulses, that tends to increase > turnaround times. Again, the figure is statistical. Compared to a lot of other standards organizations, the IETF volume is not so bursty (such as after a plenary where lots of documents are approved). > > * There's no discussion of the interaction between the > requirement to > validate format languages (in 3.5) and post-approval > turnarounds. > Yet if the Editor is validating ASN.1 or the like, that > will delay a > document. (And such validation can't occur in the > earlier phases > as the ASN.1 may change). Formal language validation can take time. It is not really possible to list all the special cases that could take time. The goal is that even including these cases the average is under one month. > > Note that I'm all in favor of a tracking queue and measuring > how fast things > pop out. But a one-size fits all view doesn't work. If an > RFC arrives with > all the lights on (100+ pages of ASN.1 in a batch of 10 RFCs from the > latest IETF), don't expect swift turnaround. > > I also had trouble with 4.2. The statement is the queue length should > show no growth trend. In government this is known as an > unfunded mandate :-). > Keeping queue lengths short if the rate of document arrival > increases costs > money (cf. professional society journal queues). Very true. Since we don't talk about money, all these requirements are an unfunded mandate. If the technical publisher becomes overloaded, then something has to give. And that may mean more money or reduced processing of each document. A disclaimer can be added that this may require adjusting resources if the input load increases over time. What this requirement captures is the desire by the IETF that we can achieve at least steady state. Contractual mechanisms to accomplish this are outside the scope of this document. > > Craig > > E-mail: [EMAIL PROTECTED] or [EMAIL PROTECTED] > > ___ > 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
