[Top] [All Lists]

Re: Specification "NOTE" paragraphs and normative language

2008-05-18 16:20:38

--On Sunday, 18 May, 2008 07:11 -0700 Dave Crocker
<dhc(_at_)dcrocker(_dot_)net> wrote:


A private comment on the BATV specification raises a basic
point about specification writing that I thought worth
pursuing independently:

Some normative statements are placed in a paragraph labeled
"NOTE:" so as to emphasize the requirement of the text.  It
has been suggested that that label actually implies less
importance, not more.  (In regular prose, a footnote, for
example, is indeed secondary to the main text.)

I think it is worth distinguishing text that is secondary from
normative text that is being emphasized.  So I'm inclined to
agree that "NOTE:" should be used for non-normative stuff.

That leaves the question of what convention is appropriate for
marking emphasized normative text.

I don't have a ready suggestion, so I thought I'd ask you


I think SM is basically right about this.  Let me elaborate...

Having used the "Note" convention (following Jon Postel and RFC
1123 in the case of mail specs), I'd offer the hypothesis that
this is either a non-problem or one that cannot be fixed by
changing terminology.  "Note" is, and should be, used to call
attention to something that might not be obvious from the
preceding or surrounding text.  If the material being noted is
normative, it will ordinarily contain text that makes that very
obvious from context, e.g., one or more of the 2119 words will
be present.  Otherwise, using 2821bis as an example, it looks
like these are purely explanatory, introduce implicit cross
references, or are qualified by terms like "Historical".  

There are exceptions and marginal cases.  One of them appears in
the I-D boilerplate, where "Note" is used to introduce a comment
about "other" I-Ds that may, by now, be largely irrelevant but
which is still mostly explanatory.

My concern is that, if we try to create differentiation, using,
e.g., "Note" and "Note well", "Normative note" and
"Informational note", or "Note-type-1" and "Note-type-2", the
careful readers won't be helped and the less-careful ones won't
notice and appreciate the difference.  Worse, authors and
editors will get it wrong sometimes and that will create far
more confusion than we have today.  We will also open ourselves
to yet another opportunity for battles with IESG members who
would rather find editorial rules to enforce uncritically than
to think carefully about readability and individual situations.
I believe that would be a net loss; YMMD.