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

Pekka Savola pekkas at netcore.fi
Thu Sep 2 23:31:49 PDT 2004


On Thu, 2 Sep 2004, Paul Hoffman / VPNC wrote:
> 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.

OK, I agree that these are not so interesting.

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

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
 - section 2.10, 2nd and 3rd paragraph
 - section 2.11, the paragraph about not being updated in the 
documents themselves, and reference to the RFC index
 - section 2.14
 - section 3.1 (12)
[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]
 - section 4.6, esp. 1st paragraph
 - appendix C as an appendix

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

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.

For example, I've been extremely happy with a dozen or so drafts by
just using my favourite editor to edit the .xml file manually, and use
the web interface at xml.resource.org to produce the text version.  
I've never even tried to compile the program, or care to do that.  
(There are good reasons to use the web interface: for example, you
don't need to have a local copy of the references, you can just do
them automatically.)

There are even a couple of copies of .xml templates which should allow
one to "learn as you go", without having to learn it the hard way.  
One of these should probably end up in the EDU team web site,
RFC-editor website, or at xml2rfc web site.

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

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

True enough ;-) -- but I think there's some rough consensus about this 
except from the location of appendices wrt references.

The reason I say this is because sometimes folks put e.g., 
Acknowledgements or Security Considerations in appendices (after the 
References).

rfc-editor-rfc2223bis-08.txt includes a pretty good order, though by 
default I'd change the order or references and appendices.

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

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.

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

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

However, I agree that something more should be there than just the
name + affiliation and the email address.  That's why I've personally
included the city and the country as well -- should be sufficient for
disambiguation.

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

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

Well, if that hurts too much, you could state that the boilerplate, 
abstract and ToC must be unnumbered sections.
 
-- 
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