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

Dave Crocker dhc at dcrocker.net
Mon Nov 5 15:51:33 PST 2012



On 11/5/2012 5:18 PM, SM wrote:
> 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.

Permitting blank or Independent or Retired does not assume an 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.

I agree.  However ultimately this is the choice of the author.  If the 
authors /wants/ the tag "Independent", why not let them use it.

That is, I see the text as defining some additional choices worth 
highlighting for authors for whom use of an organization name isn't the 
right choice.  Defining choices in a field like seems like goodness to me.


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

We should probably develop a style manual for writing the document about 
style...

(but pragmatically, humans process affirmative statements like this 
better than negative...)



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

I was actually quite liking this bit of text.  It was an interesting 
form of "we could do this but it would be wrong", to quote Richard 
Nixon.  On the average, people need help formulating a good Abstract and 
this highlights a possible danger of the simplest approach that people 
(often) take.

Actually I could argue for /more/ guidance, rather than less.


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

Again, this is a topic about which there has been confusion.  A document 
like this should provide reasonably clear guidance about what qualifies 
and normative and what doesn't.  (I do not, for example, that the rule 
should be left to the streams.  Consistency on this is important.)


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

+1

However, we shouldn't refer to them as uppercase terms.  We  should 
refer to them as normative directives that are typically shown in upper 
case.

As for the non-normative alternatives, there's a draft Tony and I wrote 
that provides more detail that the overly terse treatment in the current 
draft.

d/
-- 
  Dave Crocker
  Brandenburg InternetWorking
  bbiw.net


More information about the rfc-interest mailing list