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

Paul Hoffman / VPNC paul.hoffman at vpnc.org
Thu Sep 2 08:29:04 PDT 2004


Thanks for the extensive comments!

At 2:42 PM +0300 9/2/04, Pekka Savola wrote:
>I'm intrigued -- could you elaborate on what are these things which
>turn out to be irrelevant?

Well, there were many. For example, the history of RFCs is 
interesting but irrelevant to someone who is turning in their draft 
to become an RFC unless they have never read other RFCs; that is 
rare. Other things removed include the Postscript formatting rules 
(which apply to very few people and are probably best dealt with by 
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.

>As a general note, I'm not sure whether I saw the point of the
>rewrite.  Probably a lot of useful information has been lost, while
>adding some amount of new text.

If I have lost any useful information from 
draft-rfc-editor-rfc2223bis, by all means let me know.

>   But couldn't this have been done
>based on the earlier draft?

It *was* based on draft-rfc-editor-rfc2223bis. That's why I credited 
those folks in the acknowledgements (and added Jon Postel), and moved 
the acknowledgements up towards the beginning of the document.

>1)
>
>I think the section 2.1 on submission from the IETF should refer to
>the I-D guidelines document (or some other relevant documents) which
>describe additional requirements placed on the documents if they have
>come through the IETF process.

Sounds good. I pointed to that document a few paragraphs earlier, but 
it is good to say that there are some requirements on IETF-based 
submissions.

>This would seem to be useful to make sure that the readers are not
>confused to think that just doing what this document suggests is
>enough (editorially) to get to the RFC.  It might or might not be the
>case if you do an independent submission, but it certainly isn't if
>you go through the IETF (which is what the majority probably are
>doing).

Indeed. I'll add a note about that as well, since it has caused 
confusion in some working groups.

>2) IMHO, it would seem to be useful to give better guidance on the use
>of tools, i.e., to more strongly recommend and justify XML.  It's just
>*SO* much easier to get decent-looking documents with xml2rfc than any
>of the alternatives, and i believe this format is also best to the RFC
>editor.  The editors typically pick either Word or nroff (based on
>their background) and later on waste a lot of hours bashing their head
>against the wall to get out decent documents (or just push out
>not-so-great documents).

As a recent user of xml2rfc, I think it still needs a bit of work 
before I strongly recommend it. Two people I have workd with have not 
been able to figure out the TCL shell part, and it took me a while to 
get it working for me. But I certainly agree that it is better than 
the alternatives for formatting. Some of use still prefer plain-old 
text, however.

>3) the document doesn't appear to use many words to discuss the order
>of the sections.  Is this useful?

It would be useful if we could agree on them. :-)

>Most RFCs require a security considerations section that describes any
>issues that affect security on the Internet.
>
>==> isn't this required on *all* RFCs?  Lately, I've certainly never
>seen one which wouldn't have this section..

Not all security sections describe the effects on the Internet. This 
document is a good example of that.

>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
>the first-page header.  Contact information must include at least a
>postal address, a telephone number, and/or a long-lived email address.
>
>==> this is not correct.  postal and telephone address and such are
>not required.. and there are good reasons for that [I certainly
>don't want to be called, faxed or spammed by snailmail]

According to draft-rfc-editor-rfc2223bis, at least one is required.

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

>A satisfactory abstract can often be constructed from a summary of
>some of the material within the Introduction section.  An abstract is
>not a substitute for an introduction; the RFC should be self-contained
>as if there were no Abstract section.
>
>==> shouldn't you say that the Introduction is the first numbered
>section?

Only if it is true. Some RFCs have different names for the first section.

>An abstract should be complete in itself; it should not contain
>citations unless they are completely defined within the abstract.
>
>==> what are 'citations ... [that] are completely defined within the
>abstract'?  just make it a hard rule without the exception ?

I'm happy with that if other folks are.

--Paul Hoffman, Director
--VPN Consortium


More information about the rfc-interest mailing list