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

[Paul Hoffman / VPNC]

At 9:31 AM +0300 9/3/04, Pekka Savola wrote:
>OK... I guess I could check this in detail, but based on a quick scan
>compared rfc-editor-rfc2223bis-08.txt, some which at least could be
>considered to be useful in rfc-editor-rfc2223bis-08.txt:
>
>  - section 2.9, last paragraph

Good catch; agree.

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

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

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

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

>[it might also be useful to say explicitly that even if you don't have
>IANA considerations, it's good idea to say so explicitly]

Good point.

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

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

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

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

>Yes, but the security considerations *section* must still be present,
>even though the draft does not discuss security considerations, right?
>Current text could be read such that you could've omitted the section
>for this draft, and that would have been OK.

Good point.

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

>  > >  IP addresses in generic
>>  >examples should be from the private IP address spaces [BCP5].
>>  >
>>  >==> Rather, use the IP address reserved for examples, not private
>>  >address.  At least that's the IETF policy.
>  >
>>  Where is that written down? I thought I remembered that document but
>  > couldn't find it.
>
>I-D Checklist (http://www.ietf.org/ID-Checklist.html) points to
>RFC3330 and I-D.huston-ipv6-documentation-prefix.

Thanks!

>  > >A satisfactory abstract can often be constructed from a summary of
>>  >some of the material within the Introduction section.  An abstract is
>...snip...
>>... Introduction is the first numbered
>>  >section?
>>
>>  Only if it is true. Some RFCs have different names for the first section.
>
>Well, if that hurts too much, you could state that the boilerplate,
>abstract and ToC must be unnumbered sections.

Will do.


At 10:28 AM +0200 9/3/04, Henrik Levkowetz wrote:
>  > At 2:42 PM +0300 9/2/04, Pekka Savola wrote:
>>  >I'm intrigued -- could you elaborate on what are these things which
>...snip...
>  > the RFC Editor on a case-by-case basis), header and footer formats
>>  (which are added by the RFC Editor, not the person turning in the
>>  draft), and so on.
>
>Could we include the format of header and footer lines?

Not unless they are required by the RFC Editor, which they are not. 
This document is truly limited to things that authors of potential 
RFCs should know. If you want restrictions on header and footer 
content, they should go into 1id-guidelines.txt, I believe.

--Paul Hoffman, Director
--VPN Consortium