[rfc-i] Fwd: I-D ACTION:draft-hoffman-rfc-author-guide-00.txt

Pekka Savola pekkas at netcore.fi
Fri Sep 3 13:16:12 PDT 2004


On Fri, 3 Sep 2004, Paul Hoffman / VPNC wrote:
> >  - section 2.10, 2nd and 3rd paragraph
> 
> I think that's covered in section 4.6 of 
> draft-hoffman-rfc-author-guide, which points to the definitive 
> document (BCP 26) instead of repeating-with-different-words that 
> material.

Sect 4.6 seems insufficient as it could be read to discuss only the 
case of specifying new IANA codepoints from existing namespaces, not 
defining new namespaces with appropriate guidelines for assignments.

The latter seems important as many documents have forgotten to specify 
what are the new namespaces created by the specification, and how the 
allocations are to be handled in the future.

> >  - section 2.11, the paragraph about not being updated in the
> >documents themselves, and reference to the RFC index
> 
> Why is that relevant to someone who is writing an RFC?

OK, I can see why it need not go here.  I think this would have been 
useful because it underlines the fact that the RFCs are not changed 
after publication; the language in section 4.4, if not read carefully, 
could be interpreted so that "updates" could be used to change the 
text in the previous RFC (the RFC itself).
 
> >  - section 2.14
> 
> Fully disagree here. The RFC Editor does not consistently enforce 
> this rule (nor should they, in my opinion). RFC 2119 stands on its 
> own without the need to repeat parts and to restate other parts.

Well, this seems to be a pretty hard IESG rule at least, i.e., if you 
use uppercase words SHOULD, MUST, etc., you should either specify what 
you mean by them or refer to RFC 2119.  Seems like a good idea to me.

> >  - section 3.1 (12)
> 
> That recommendation is rarely used by RFCs, so I removed it. It is 
> also somewhat painful for the RFC Editor to implement correctly, and 
> can cause difficulty in the author review stage (48 hour queue).

Indentation actually (IMHO) helps the readability *a lot*.  It's a
pain if you don't use an automatic formatter, of course, but a lot of
things are.

> >  - section 4.6, esp. 1st paragraph
> 
> This has nothing to do with the Internet Draft turned into the RFC 
> Editor. The RFC Editor adds their own table of contents using their 
> own tools. This is exactly one of the places that has vexed ID 
> authors who are not using tools that create TOCs, causing needless 
> hours (literally) of hassle. The suggestion for having tables of 
> contents is covered in the 1id-guidelines document which refers to 
> all IDs, not just ones being sent to the RFC Editor.

Then maybe they should be using the tools? ;-)

At least it helps my reading of the drafts a lot -- giving a good 
overview of the flow of the document.  

> >  - appendix C as an appendix
> 
> Fully disagree. The checklist mixes requirements with suggestions in 
> a way that is quite confusing. A checklist of the requirements might 
> be useful, but it would also necessarily reword the text in the main 
> part of the document.

I can live without it, just thought it would be useful.
 
> >The point I have tried to make multiple times is that you *don't* need
> >to download the xml2rfc program, or an xml editor to do xml2rfc.
> 
> Sorry, I missed that. And it is a very good point that I'll add.

Great.
 
> >  > Some of use still prefer plain-old text, however.
> >
> >And that causes no end of trouble, e.g., when the ToC gets out of date
> >(or must be done manually, or is at the end of the draft), the
> >boilerplates are invalid, text goes beyond 72 chars/line, references
> >aren't kept up-to-date automatically, etc.etc. -- both from the people
> >who want to get the drafts to a good quality and must waste time on
> >commenting, and the folks who need to fix all of these manually.
> 
> I find plain-old-text easier even with all those things, but maybe 
> I'm abnormal. I also didn't add it as a "suggested tool".

Doing it yourself obviously is more "controlled", and some prefer it,
of course.  The point just is that for the generic audience (those who
need to read the RFC), it'd produce an incredible amount of pain in
the end, and using the best tools from the start is the best approach.
 
> >  > >Th author's address section, which is required for all RFCs, gives the
> >>  >name(s) and contact information for the author(s) who are listed in
> >...snip...
> >  > >don't want to be called, faxed or spammed by snailmail]
> >>
> >>  According to draft-rfc-editor-rfc2223bis, at least one is required.
> >
> >Well, RFC editor doesn't seem to be requiring them, as multiple RFCs
> >have been published without such information (e.g., mine, but probably
> >others' as well).
> 
> Could you point to a specific RFC? Every one I have seen has at least 
> an email address.

Sorry if I said this in a confusing way -- an email address needs to
be present (except for those people who've deceased during the
process);  was arguing againt requiring the other kind of contact
info, like telephone or fax numbers, snailmail addresses, etc. (as 
these aren't required today).

-- 
Pekka Savola                 "You each name yourselves king, yet the
Netcore Oy                    kingdom bleeds."
Systems. Networks. Security. -- George R.R. Martin: A Clash of Kings



More information about the rfc-interest mailing list