[rfc-i] Comments about draft-flanagan-style-00
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.
More information about the rfc-interest