[rfc-i] Comments about draft-flanagan-style-00

SM sm at resistor.net
Mon Nov 5 14:18:09 PST 2012


Hi Heather, Sandy,

I hope that you are both enjoying the fine weather in Atlanta.  I 
have a few comments about draft-flanagan-style-00.  In Section 4.1:

   "If an author cannot or will not provide an affiliation for any
    reason, "Independent", "Retired", or some other term that
    appropriately describes the author's affiliation may be used.
    Alternatively, a blank line may be included in the document header
    when no affiliation is provided."

There is an assumption in the above that everyone has some 
affiliation.  The author I know about does not provide affiliation as 
it is an individual effort instead of a company-sponsored effort.  I 
find the usage of "Independent" confusing as it is difficult to tell 
whether that is a company or not.  It's easier to use a blank line in 
such cases.  I suggest rewording the about as "an author not having 
an affiliation, i.e. it's an individual effort" and use the blank 
line for that.

In Section 4.3:

   "Every RFC must have an Abstract of a maximum of 20 lines."

You could reword this sentence by saying that the Abstract must not 
have more than 20 lines.  It is clearer.

   "Simply copying and pasting the first few paragraphs of the
    Introduction is allowed, but it may result in an Abstract that is
    both incomplete and redundant."

I suggest removing this.  It will encourage people to copy and paste 
as it is allowed.

In Section 4.8:

   "Reference lists must indicate whether each reference is normative
    or informative, where normative references are essential to
    implementing or understanding the content of the RFC, and
    informative references provide additional information."

Discussions about references lead to, well, IETF discussions. :-)  I 
suggest ending the sentence after the comma, then proceed with the 
explanation of what constitutes a normative reference.  By the way, 
some documents tend to have a long list of references.  It's more 
work for reviewers.  It would be good if you could explain to people 
during the tutorials to refrain from such practices as people 
actually have to go and read these documents.

   'To forestall confusion between uppercase conformance terms and
    their lowercase equivalents, some authors use words and phrases
    such as "mandatory", "ought to", and "might" instead of "MUST",
    "SHOULD", and "MAY".'

My understandaing of these upper-case words is that they are for 
interoperability and not for conformance.  There are sometimes uses 
for basic assumptions, e.g we assume that the earth is flat.  I 
suggest removing the "mandatory" or "ought to" guidance as we already 
have enough fights about what the RFC says.

   'For example, we recommend the use of "TBD1",
    "TBD2", etc., in the IANA Considerations section and in the body
     of the document.'

Please expand TBD on first use.  It may not be clear to non-Englizh speakers.

   "Contact information must include at least one, and ideally would
    include all, of a postal address including the ISO 3166 country
    code, a telephone number, and a long-lived email address."

It is suggested that the authors of this draft follow that guidance.

Regards,
-sm



More information about the rfc-interest mailing list