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

Pekka Savola pekkas at netcore.fi
Thu Sep 2 04:42:01 PDT 2004


On Wed, 1 Sep 2004, Paul Hoffman / VPNC wrote:
> Please let me know if you think this is a useful document. It is 
> always sad to hear people say that they spent hours doing things for 
> Internet Drafts that turn out to be irrelevant to getting published 
> as an RFC,

I'm intrigued -- could you elaborate on what are these things which 
turn out to be irrelevant?

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.  But couldn't this have been done 
based on the earlier draft?

...

Meta-question:
--------------

An Internet Draft that is submitted to the RFC Editor enters the RFC
Editor's publication queue; the queue is viewable at the RFC Editor
Web site.

==> does RFC-editor do some kind of submission tracking?  I've heard
reports of these submissions sometimes getting lost without a reply or 
appearance in the publication queue.  Maybe one should say a few words 
how soon one should expect the document to be seen in the queue (and 
if not, complain about it)?

major comments:
---------------

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.

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

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

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

A couple of editorial or minor comments:
----------------------------------------

To maintain the integrity of the RFC document series and to avoid
wasting scarce publication resources, the RFC Editor may reject an
independent submission because its content is uninteresting or
irrelevant, or because its editorial quality is acceptable.

==> s/acceptable/unacceptable/

Once the RFC Editor has determined that an independent submission is
acceptable,

==> s/Once/Once and if/ (?)

RFCs published this way have often been not as useful as those in
plain ASCII because many people do not know to retrieve the alternate
versions,

==> s/those/those only/ (to drive the point home that even if you 
PS/PDF, you'll have to do the text version as well) -- this might 
possibly be underlined further.

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

The distinction between normative and informative references is often
important.  The IETF standards process and the RFC Editor publication
process need to know whether a reference to a work in progress is
normative.  A standards-track RFC cannot be published until all of the
documents that it lists as normative references have been published.  
In practice, this often results in the simultaneous publication of a
group of interrelated RFCs.

==> there should probably be a reference pointer here.

4.9 Author's address section

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]

 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.

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?

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 ?

When turning in an Internet Draft, do not fill the text with extra
spaces to provide a straight right margin.  Do not right justify the
text.

==> s/margin. Do/margin, i.e., do/

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