Re: draft-rfc-editor-rfc2223bis-04.txt

[Bob Braden <braden@ISI.EDU>]

John,

We are very grateful for the work you put into reading and commenting
on the document.
  *> 
  *> IESG,
  *> 
  *> (I am copying the RFC Editor, since many of these comments are 
  *> general editorial and policy ones, and Scott in his capacity as 
  *> editor of the IPR-Submission document as well as 2026.)
  *> 
  *> My apologies for not sending this sooner, but I only had the 
  *> opportunity to read all of it carefully this weekend.
  *> 
  *> Summary: While I don't think it is the intent, this document 
  *> appears to be setting policy that is contradictory to, or goes 
  *> beyond, the intent (and sometimes letter) of current operating 
  *> procedures, the text in 2026, etc.    That ought to be cured, in 
  *> order to avoid turning a confusing situation into a complex mess 
  *> with many opportunities for misunderstanding and 
  *> finger-pointing.  In addition, some sections of the document do 

While it comes as a slight surprise to us that people perceive an actual
conflict between this document and COPs, we certainly agree that this must
be fixed.

  *> not reflect the high editorial quality that the RFC Editor has 
  *> apparently come to expect from other authors and editors and 
  *> others would appear to me to increase, rather than reduce, 
  *> confusion.

;-)

  *> 
  *> Details and examples...
  *> 
  *> (1) Section 1.3.1, first paragraph, "All RFCs have been I-Ds, 
  *> but..." is manifestly false since many RFCs were published 
  *> before I-Ds appeared on the scene.

Accepted.  The sentence, while once vital, is not really needed any
more anyway... the community now seems to understand well the difference
between IDs and RFCs, so we'll simply remove the sentence.

  *> 
  *> (2) Section 1.3.1, second paragraph, "The Internet Draft must 
  *> include boilerplate that allows...".  The boilerplate required 
  *> is, I believe, an open issue as we rework ipr-submission.  I've 
  *> raised the argument there that, especially for individual 
  *> submissions, it should be possible to prohibit any tampering 
  *> with I-Ds (and to require strict interpretation of the "six 
  *> month expiration" rule) while granting all of the needed 
  *> permissions for RFC publication.  The reference to 

We don't understand what you want us to do about this.  As we understand
it, the sentence in question is correct.

  *> 1id-guidelines is also problematic, since it is an extremely 
  *> normative reference (see immediately below) to a document that, 
  *> in practice, changes (or not) at the whim of the secretariat and 
  *> for which there are no established change control procedures or 
  *> tracking mechanisms.
  *> 
  *> (3) Under the definitions of 2.7, the reference to 
  *> 1id-guidelines is normative in the extreme: this document sets 

Sorry, but we fail to understand what you mean by "normative in the
extreme."  In any case, what you say about it makes no sense to us.  On
the contrary, it should be clear that this document is self-standing.
The reputed fact that I-D formatting has deliberately been defined to
be consistent with RFCs (a statement that was becoming true over the
past few years, although this tide may have turned recently) does not
in any way make 1id-guidelines a prerequisite for RFC 2223bis.
(In fact, the reference is informative.)

  *> up a requirement about text that must be included, then refers 
  *> to 1id-guidelines for the rules about that text.  Hence, it is 
  *> impossible to meet the requirements of this document without 
  *> reading, understanding, and following that one.   This points 
  *> out a problem with the normative/non-normative distinction that 
  *> I've seen a few times lately (and IESG may be seeing more 
  *> often): authors and editors are classifying marginal (or even 
  *> very clear, as in this case) materials as non-normative in order 
  *> to bypass the somewhat more strict checking rules for normative 
  *> documents.  That serves us even less well than having the two 

"Points out" implies that the RFC Editor deliberately tried to deceive
you in this case.  It should be clear that there is no substance in this.

  *> lumped together.  If we can't figure out how to stop it, I would 
  *> encourage the IESG and the RFC Editor to reconsider the 
  *> distinction.

That seems like an over-reaction to a less-than-perfect world.

  *> 
  *> (4) Section 1.3.1, third paragraph.  The last I heard, 
  *> submissions from the IAB, or under IAB management (e.g., IRTF 
  *> documents approved for publication by the IAB) were handled 
  *> differently from either "individual submissions" or "IETF 
  *> documents" (processed first by the IESG).  That distinction, 
  *> which was rather carefully worked out, seems to have gotten lost 
  *> in this draft.

Accepted. We have been fuzzy about this, in part because IAB documents
are not very numerous.  However, as someone else noted, our flow chart
DOES show the IAB, so we ought to mention that case.

IRTF documents we have been treating as individual submissions, and
that generally seems to fit.  In fact, I have been told in the past
that the IESG treats IRTF documents as individual submissions.

  *> 
  *> (5) Section 1.3.1, first bullet, first paragraph.  Several of us 
  *> have worked very hard to eliminate the ambiguities that have 
  *> permitted individual submissions of informational document to go 
  *> directly to the IESG, bypassing the documented processes, 
  *> getting extra priority as a result, and creating priority 
  *> problems within the IESG.   The text "however the IESG may 
  *> occasionally accept..." opens that problem back up again.  I 
  *> believe the text should either explicitly identify this 
  *> statement as applying to standards-track non-WG documents or 
  *> should point to the place where the occasional/exceptional 
  *> procedure is documented.  See also (7), below.

Accepted.  We will strike the sentence, although the "occasionally"
seems to us sufficient, and we see no particular reason to tie the
IESGs hand from ever submitting non-WG Informational documents to us.

  *> 
  *> (6) Section 1.3.1, first bullet, second paragraph.  "TYI" should 
  *> probably be "FYI".  But the IESG should consider whether, with 
  *> the User Services area closed, FYI documents are largely an 
  *> historical artifact.  Certainly a number of documents on the FYI 
  *> list are ripe candidates for reclassification to "Historical".
  *> 
  *> (7) It is not clear to me that the RFC Editor should be 
  *> obligated to publish anything the IESG signs off on ("submits"). 
  *> Clearly, standards-track documents must be published.  But I'm 
  *> less sure of WG-produced informational or experimental ones, and 
  *> much less sure about individual informational submissions that 
  *> have somehow gotten IESG endorsement.   On those, it seems to me 
  *> that the very essence of an independent RFC Editor is that they 
  *> should be able to push back if they believe a document is 
  *> inappropriate.  I wouldn't expect they would do that very often, 
  *> and it would presumably create a crisis if they did, but that is 
  *> another matter.

Well, in fact we have pushed back exactly once (the MPLS paordy), and
yes, it did create a crisis.  In any case, we thought that "reserves
the right to discuss" was sufficient.

  *> 
  *> (8) Section 1.3.1, second bullet, third paragraph.  I believe 
  *> that the RFC Editor also reviews individual submissions for 
  *> relevance and appropriateness and, indeed, that the review for 
  *> those characteristics is the most important RFC Editor 
  *> discretionary function.   Such a review is implied by the 
  *> following paragraph, but it should be called out along with 
  *> "editorial issues" here (or the two paragraphs rewritten and 
  *> their order reversed).

Accepted.

  *> 
  *> (9) Section 1.3.1, second bullet, paragraph five.  We have had 
  *> problems with the notion of RFC Editor review of individual 
  *> submissions ever since we changed the procedures to require that 

I would change yhour "require" to "request", as more nearly reflecting
what has happened -- or drop "require" altogether, as too anal ;-)

We are not aware of "problems with the notion" -- the IESG asked for
us to do it, and we were under the impression that the IESG was
generally grateful for the results (if they aren't, they should
be!)

  *> review before the document went to the IESG.  As one of the 
  *> people who was at least partially responsible for the change 
  *> (Scott and I can't remember who proposed the idea), the notion 
  *> was to reduce load on the IESG by eliminating any document that, 
  *> on the basis of relevance and appropriateness, the RFC Editor 
  *> was not going to publish even if the IESG found that it was not 

And to raise the editorial quality before the IESG had to read it.

  *> harmful or an end run.  If the review was conducted the way we 
  *> anticipated (and I thought we had consensus at the time), it 
  *> would also reduce overall load on the RFC Editor by preventing 
  *> having to do anything twice and some things even once.  The 
  *> model was that
  *> 
  *> 	(i) The document would go to the RFC Editor, as provided
  *> 	in 2026.
  *> 	
  *> 	(ii) The RFC Editor would perform a preliminary review,
  *> 	focusing on relevancy and appropriateness and the
  *> 	general question of whether it appeared possible to edit
  *> 	it into an acceptable form (after a reasonable number of
  *> 	iterations with an author who was reasonable and
  *> 	cooperative).   If the answer to any of those review
  *> 	questions was "no", the document would be returned to
  *> 	the author with appropriate instructions.
  *> 	
  *> 	(iii) If the answer to those three review questions was
  *> 	"yes", the document would be sent to the IESG --without
  *> 	further editing-- for review on the questions of

This is not the practice we have been following, or what we think we
were asked to do. It makes most sense to us to get the editorial work
largely out of the way first, and it seems more efficient that way.


  *> 	end-runs and possible harm to the network.  Those two
  *> 	conditions are the only ones for which 2026 gives the
  *> 	IESG authority to review a document or ask for changes:
  *> 	"ensur[ing] its technical quality", as suggested by this
  *> 	document, is not on the list.   IESG members may, of
  *> 	course, comment to the author on technical quality, or
  *> 	may offer opinions to the RFC Editor on whether it
  *> 	should be published, but so can any other member of the
  *> 	IETF community.  They have no special standing as the
  *> 	IESG in that regard, and any sort of "change the
  *> 	document to make AD XX happy, or it isn't going
  *> 	anywhere" interactions are process violations.

But, of course, we all recognize that the IESG definitely DOES
review individual submissions for what they perceive to be
technical quality.  A few individual submissions have been
inappropriately killed by the IESG when individual ADs had
different technical ideas, in our opinion.  But it is an
imperfect world, and we muddle along.

  *> 	
  *> 	(iv) Only when the IESG acknowledges (by default if
  *> 	necessary) that the document does not constitute an end
  *> 	run and isn't proposing something that would cause
  *> 	serious harm does document editing and formatting begin.

"Serious harm" is subject to a wide interpretation.  The IESG is very
properly protective of the Internet technology, and they may at times,
with all good intent, over-state the risks.  Remember Mohsen Banen?

  *> 	This permits any edits that are required as the result
  *> 	of IESG-requested changes to be incorporated into the
  *> 	first editing pass.  If the IESG generates as "please do

This would put the IESG in the position of being document editor, a task
that I don't think they really (should) want to perform any more than
they have to already.

  *> 	not publish" and the RFC Editor agrees, the document
  *> 	disappears without any editing time being spent.   By
  *> 	contrast, the procedure outlined in the subject
  *> 	paragraph requires that they document be completely
  *> 	edited and formatted, sent to the IESG, and then

No, we do not insist on strict formatting, as long as the document is
reasonably readable.  During the final publication process we expect
additional editorial issues to arise and be corrected.  But we do expect
that a document submitted as an RFC should already generally follow
the defined RFC format and be clearly organized and formatted with
at least a bit of care, and we think that the IESG should expect
no less in an individual submission that we send to them.  It is
sad how few individual submissions are even close.

  *> 	potentially discarded or extensively re-edited and
  *> 	reformatted.  That doesn't benefit any of the IETF, the
  *> 	IESG, the authors, people waiting for publication of
  *> 	other documents, or whomever is paying the bills.

We believe this is not a correct reading of the situation.

BTW, you missed "the the". ;-)


  *> 
  *> (10) Section 1.3.1, second bullet, paragraph six.  This 
  *> explanation of what happens when the IESG is unhappy with a 
  *> document does not reflect actual practice, at least as I 
  *> remember it.  The IESG can either request that the document not 
  *> be published or that a disclaimer be attached to it.  Those are 
  *> two separate types of requests: "DNP or at least attach a 
  *> disclaimer" is a third possibility, but less common.  When the 
  *> RFC Editor gets _any_ of those inputs, they may:
  *> 
  *> 	(i) Reject the document, even if the IESG only requested
  *> 	a disclaimer.
  *> 	
  *> 	(ii) Attach a disclaimer and publish.  If the IESG
  *> 	requested non-publication, this presumably requires
  *> 	going back to the IESG and negotiating a disclaimer.
  *> 	
  *> 	(iii) In theory, publish the document as submitted
  *> 	(without a disclaimer), indicating to the IESG that they
  *> 	are welcome to submit a dissenting RFC.
  *> 

We do not believe in (iii).  We believe that if the IESG wants a
disclaimer, the IESG should have a disclaimer.  Far better to
publish with baggage than not to publish at all, in our view.
Let the reader decide.

We do not understand your point here.  The words we have written
seem to correctly state the alternatives.

  *> I believe that the RFC Editor's doing something contrary to IESG 
  *> wishes in these matters should be a rare situation indeed.  But, 

We don't disagree with this.

  *> to the extent to which we want to have an independent RFC Editor 
  *> process, I believe that they must have the right to make those 
  *> decisions.  If the community believes there is a problem with 
  *> that level of independence, then we should be devising a review 
  *> and appeal procedure, not crippling the RFC Editor's choices in 
  *> this type of document.
  *> 
  *> (11) Section 2.4, paragraph one.   I believe that the list of 
  *> reasons for "secondary or alternative versions" should now 
  *> include "characters" as well as [fancy] diagrams and graphs.

Accepted.

  *> 
  *> (12) Section 2.4, paragraph two ("The continued...").  The 
  *> notion of permanence of the ASCII-based format belongs in this 
  *> explanation.  To at least some fraction of the community, I 
  *> think a significant one, the strongest argument for ASCII is 
  *> that documents in plain ASCII can still be read, without keeping 
  *> legacy tools around just for the purpose, a decade or two later. 
  *> That is not the case, so far, for any of the alternate formats 
  *> that have been proposed over the years (although 
  *> first-generation Postscript is getting close).  Similarly, one 
  *> of the reasons line-ending hyphenation has always been 
  *> discouraged (section 3.1(6)) is that it causes problems with 
  *> grep-like searching of documents.

Accepted.

  *> 
  *> (13) Section 2.4, paragraph four ("If there is...").  The 
  *> reference to section 2.4 probably doesn't belong here, since it 
  *> is section 2.4.

Accepted! 

  *> 
  *> (14) Section 2.7, paragraph 4.  This paragraph, as written, 
  *> seems to make the definitions of RFC 2119 a requirement for 
  *> standards-track documents which use those words.   Our principle 
  *> has been that the 2119 are normative for the standards-track 
  *> documents that chose to use them, but that such documents may 
  *> adopt other definitions.  The Instructions for RFC Authors 
  *> should not change that established rule by requiring that, "if 
  *> these words are used and capitalized", RFC 2119 must be used and 
  *> cited.
  *> 

Accepted.

  *> (15) Section 2.9, paragraph 2.  The last I heard, the IETF 
  *> didn't have "members".   I believe "participants" would be more 
  *> appropriate.
  *> 
Accepted.

  *> (16) Section 2.11.  To the extent that this document should 
  *> address the "update" and "obsolete" relationships for 
  *> standards-track materials, it is important, IMO, to clarify 
  *> whether a document at Proposed can obsolete, or even update, one 
  *> at Standard.  If the answer is "yes in some cases", I believe 
  *> that decision should explicitly involve the IESG, rather than 
  *> being an exclusively RFC Editor decision.

This issue needs more discussion and clarification.

  *> 
  *> (17) Section 2.13.  I believe that "satire" in the first 
  *> sentence should be "satirical".  The RFC Editor is to be 
  *> congratulated on having this subsection appear as number 13.

You noticed! ;-)

Accepted.

  *> 
  *> (18) Section 3.1(2), second paragraph.  I think this should be 
  *> "protocol conventions require" or some other variant.  The 
  *> present text does not parse well.

Maybe...

  *> 
  *> (19) Section 3.1 and 3.3 generally.  As highlighted by a recent 
  *> set of discussions on the IETF "problem-statement" list, it is 
  *> important for the RFC Editor (and, where appropriate, this 
  *> document) to distinguish between the format(s) that are expected 
  *> as input and those that characterize a finished RFC.  For the 
  *> former, the goal should be to maximize the efficiency of both 
  *> authors and the RFC Editor.  IMO, formatting details --including 
  *> pagination, headers and footers, and table of contents page 
  *> references that depend on them-- that the RFC Editor will just 
  *> need to remove before inserting their own as part of the nroff 
  *> conversion process should not be required and might 
  *> appropriately be actively discouraged.

Not sure about this one.  If you send us an exactly formatted RFC, we
can feed it to a script that will deduce and add the correct nroff
directives to reproduce that RFC.  And, it seems that it is less work
for us when the RFC you submit is ALMOST correctly formatted.  But, if
there were a clear advantage to submitting totally unformatted RFCs, I
guess we could format them.

The implications would need to be further explored, but the idea of
avoiding page formatting in I-Ds and adding it to published RFCs does
seem reasonable, as one alternative procedure.

  *> 
  *> (20) Section 4 (introduction/ section list).  I believe that the 
  *> list would be more useful if "optional" were replaced by 
  *> something like "required under some circumstances" for sections 
  *> 3 and 12.  Similarly, the IESG note (section 4) is _never_ 
  *> optional, it is either required or prohibited, and never 
  *> supplied in a document-as-submitted in any event (nor are 
  *> several of the header items, including especially "Category", 
  *> listed in 4.1.   Some of this material belongs in a separate 
  *> document called, perhaps, "How to Read an RFC".

Accepted.

  *> 
  *> (21) Section 4 (introduction) and 4.7.  I have run into a few 
  *> documents of late (more at the I-D stage than after RFC 
  *> publication) that are so abbreviation-laden, and sufficiently 
  *> long, as to be essentially unreadable.  For those documents, it 
  *> may be time to start requiring either a glossary or an index of 
  *> special terms.  I think the document should explicitly call out 
  *> that possibility.

The IESG sometimes asks for glossaries and we could do so too for
individual submissions.

However, recently we have noted a frightening increase in the following
editorial abomination: a content-free Introduction section followed by
a Glossary section with terms in alphabetical order, all intertwined in
some complex way.  You have to be a computer to parse the thing and
figure out what the Hell the document is trying to say.  Then sometime
later there may be, in section 2 or 3 or 4, the introductory
explanation that you needed before you got to the glossary.  You end up
rereading the glossary 30 times, trying to thread through the
intertwined definitions.  I don't know where people picked up this
abominable format, but I suspect it is from other standards bodies.
Jon left us with a legacy of a large corpus of technical documents
written with grace and clarity.  We are losing it, fast.

If we had our way, we would REQUIRE that glossaries come at the
END of a document, forcing a proper introduction.  A glossary
should be for REFERENCE, not to make a document that only a computer
could love.

  *> 
  *> (22) Section 4.12 on reference formats. As discussed in another 
  *> context some months ago, the [nn] style of references, as used 
  *> and therefore implicitly recommended in this document, is 
  *> somewhat problematic when used with a split (normative/ 
  *> non-normative) references section.  Part of the problem is 
  *> illustrated on pages 33 and 34 (see (26) below), where the 
  *> numbers appear in a somewhat-odd order.  It would be very 
  *> helpful if the RFC Editor were extremely clear about what it 
  *> expects (and would permit) in these cases, perhaps noting that 
  *> most style manuals that recommend the [nn] form insist that the 
  *> references be numbered strictly in the order in which the 
  *> targets appear (which pages 33-34 violate).

We just recently realized that we confused people about what we
mean by "reference"; many people are taking it to mean "citation".
We agree that numbered citations cause confusion with the Normative/
Informative split, and we should set the right example.

Accepted, mostly.

Another issue that is bothering us these days is whether
non-standards-track documents can EVER have Normative references.  We
suspect that only standards-track documents should make the N/I
distinction in its references.

  *> 
  *> (23) Section 4.12 on I-Ds and URLs.   While I completely agree 
  *> on the importance of citing I-Ds only non-normatively (and with 
  *> "normative" carefully and accurately interpreted, see (3) above) 
  *> and as "work in progress", I think we do a disservice to the 
  *> reader by not explicitly identifying these as I-Ds and giving a 
  *> date.  Someone who wants to find those "works in progress" is 
  *> entitled to hints as to how to try to find them and which one 
  *> was referred to in constructing the RFC.  Otherwise, they aren't 
  *> references at all, just a rather vague form of handwaving.

This is problematic.  Once you say a date, you are implying a
particular version of the I-D, but since all versions are (or,
should be, we strongly believe) ephemeral, this seems undesirable.

  *> 
  *> (24) Appendix B: The discussion of Microsoft Word should 
  *> reiterate that RFC 3285 and its template have been tested only 
  *> on fairly simple documents and may not be suitable for more 
  *> complex ones.

Accepted.  Maybe this should not even BE in this document, but only
on the web page.

  *> 
  *> (25) Appendix C, topic A.7 (and maybe C.1): We forbid categories 
  *> from appearing in I-Ds.  This seems to imply that the RFC Editor 
  *> requires that the category be filled in correctly before the 
  *> document reaches them.  But, in theory, the only way in which a 
  *> document reaches them is as an I-D.  There is a bit of a problem 
  *> with this (and elsewhere).
  *> 

Yes.  Presumably the category is passed out-of-band, in the IESG's
message to the RFC Editor.

  *> (26) Page numbers and section numbers.  It has been a 
  *> long-standing principle that we try to avoid page number 
  *> references into RFCs, instead using numbered sections or the 

Yes.

  *> equivalent.  The list of sections in section 4 of this document 
  *> appears to follow that model, the document itself does not, 
  *> resulting in unnumbered appendices and subsequent materials. 

The Appendices are not "unnumbered"; they are designated by a letter.
This is in accord with publication convention as we know it.
Since the unnumbered/unlettered sections are all conventionally
required and named, there is no problem referencing them without
page numbers.

We don't see a problem here.

  *> While I believe the latter is less desirable (and inconsistent 
  *> with many recent RFCs), I believe even more strongly that we 
  *> should settle this issue once and for all, establish a norm for 
  *> it, and get it into this document.   Granted "appendices before 
  *> acknowledgements" make numbering look a little strange, but, 
  *> from both a formatting and "finding things in the text" 
  *> standpoint, having security and IANA considerations, etc., 
  *> unnumbered makes them hard to spot.   I believe, fwiw, this is 
  *> one of the reasons why ISO adopted the term "annex" in 
  *> preference to "appendix" -- they put them where logic dictates 
  *> and then just number them as sections (I don't recall whether 
  *> their style manual calls for
  *> 
  *>       85. Text section
  *>       86. Annex 1
  *>       87. Annex 2
  *>       88. More text
  *> or for
  *>       85. Text section
  *>       86. Annexes
  *>       86.1. Annex 1
  *>       86.2. Annex 2
  *>       87. More text
  *> but can look it up if that would be useful.
  *> 

Interesting observation.  We have been struggling with specifying
the order; people keep asking for more and more specificity, but,
following the Internet Way, we want to specify the minimum necessary
rules.

Many authors like to put Appendices at the end, but that often makes
it really hard to find the references, so we prefer the references
near the end.

We are happy to consider the Acknowledgments and Security Considerations
sections to be part of the body, and hence (normally) numbered.
Here is where your Annex idea does seem to work better.  We need
to think more about this.

RFC Editor


  *> regards,
  *>     john
  *> 
  *> 
  *> 


----- End Included Message -----