Subject: [Gen-art] Re: Last Call: draft-heard-rfc4181-update (RFC 4181 Update to Recognize the IETF Trust) to BCP [WAS: Gen-art review of draft-heard-rfc4181-update-00.txt]

From: "C. M. Heard" <[email-masked]>
Date: Mon, 12 Feb 2007 10:26:13 -0800 (PST)

On Tue, 23 Jan 2007, Gonzalo Camarillo wrote:
> I have been selected as the General Area Review Team (Gen-ART)
> reviewer for this draft (for background on Gen-ART, please see
> http://www.alvestrand.no/ietf/gen/art/gen-art-FAQ.html).
>
> Please resolve these comments along with any other Last Call comments
> you may receive.

I will do so, and in that spirit I'm posting my response to the IETF 
list with the subject line changed.  My apologies for the delay in 
replying.

> Draft: draft-heard-rfc4181-update-00.txt
> Reviewer: Gonzalo Camarillo <[email-masked]>
> Review Date: 23 January 2006
> IETF LC Date: 16 January 2006
> 
>
> Summary:
>
> This draft is basically ready for publication, but has nits that should
> be fixed before publication.
>
>
> Comments:
>
> The title of the draft could be more explicit. Now it mentions RFC 
> 4181. It could also indicate that it is an update to the 
> Guidelines for Authors and Reviewers of MIB Documents.

I disagree with this comment -- I believe that doing as it suggests 
would make the title unnecessarily long.  Note that the Abstract 
already spells out the full title of RFC 4181.

> Acronyms (e.g., MIB) should be expanded on their first use.

The only places where the acronym "MIB" is used are in the Abstract 
and the References, where the title of RFC 4181 is quoted.  The 
acronym is not expanded in that title, and it would be inappropriate 
to do so in a citation, which is supposed to quote the exact title 
of the document being cited.

Also, I believe that "MIB" qualifies as an appreviation that is so 
firmly extablished in IETF usage that its use is very unlikely to 
cause uncertainty or ambiguity and so is exempt from the usual 
acronym expansion requirement.  Granted that it is not explicitly 
mentioned in http://www.rfc-editor.org/policy.html#policy.abbrevs, 
but several recent RFCs using the acronym "MIB" have appeared 
without it being expanded anywhere.  RFC 4181 and RFC 4663 are 
examples.

The only other acronym I see is IETF, and that one is explicitly 
mentioned in http://www.rfc-editor.org/policy.html#policy.abbrevs.

> The draft should be divided into pages, none of which should 
> exceed 58 lines.

Unless I'm required to make another revision for other reasons, I'd 
like to let the RFC Editor take care of that (which they will do 
anyway) ... my apologies if the lack of pagination has caused any 
readability problems.

Mike

_______________________________________________
Gen-art mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/gen-art

---

From: Gonzalo Camarillo <[email-masked]>
Date: Tue, 13 Feb 2007 09:35:56 +0200

Hi Mike,

as the review says, they are just nits. If you disagree with them, feel 
free to ignore them (as long as your AD is also OK with that, of course).

Cheers,

Gonzalo

C. M. Heard wrote:
>> 4181. It could also indicate that it is an update to the Guidelines 
>> for Authors and Reviewers of MIB Documents.
> 
> would make the title unnecessarily long.  Note that the Abstract already 
> spells out the full title of RFC 4181.
> 
> The only places where the acronym "MIB" is used are in the Abstract and 
> the References, where the title of RFC 4181 is quoted.  The acronym is 
> not expanded in that title, and it would be inappropriate to do so in a 
> citation, which is supposed to quote the exact title of the document 
> being cited.
> 
> firmly extablished in IETF usage that its use is very unlikely to cause 
> uncertainty or ambiguity and so is exempt from the usual acronym 
> expansion requirement.  Granted that it is not explicitly mentioned in 
> http://www.rfc-editor.org/policy.html#policy.abbrevs, but several recent 
> RFCs using the acronym "MIB" have appeared without it being expanded 
> anywhere.  RFC 4181 and RFC 4663 are examples.
> 
>> The draft should be divided into pages, none of which should exceed 58 
>> lines.
> 
> Unless I'm required to make another revision for other reasons, I'd like 
> to let the RFC Editor take care of that (which they will do anyway) ... 
> my apologies if the lack of pagination has caused any readability problems.
> 
> Mike

---

From: "Romascanu, Dan \(Dan\)" <[email-masked]>
Date: Tue, 13 Feb 2007 11:47:02 +0200

Mike's assessment seems reasonable to me. 

Dan

> -----Original Message-----
> From: Gonzalo Camarillo [mailto:[email-masked]] 
> Sent: Tuesday, February 13, 2007 9:36 AM
> To: C. M. Heard
> Cc: IETF; Romascanu, Dan (Dan); GEN-ART
> Subject: Re: Last Call: draft-heard-rfc4181-update (RFC 4181 
> Update to Recognize the IETF Trust) to BCP [WAS: Gen-art 
> review of draft-heard-rfc4181-update-00.txt]
> 
> Hi Mike,
> 
> as the review says, they are just nits. If you disagree with 
> them, feel free to ignore them (as long as your AD is also OK 
> with that, of course).
> 
> Cheers,
> 
> Gonzalo
> 
> 
> C. M. Heard wrote:
> >> Reviewer: Gonzalo Camarillo 
> <[email-masked]> Review 
> >> Date: 23 January 2006 IETF LC Date: 16 January 2006
> >>
> >>
> >> Summary:
> >>
> >> This draft is basically ready for publication, but has nits that 
> >> should be fixed before publication.
> >>
> >>
> >> Comments:
> >>
> Guidelines 
> > to do so in a citation, which is supposed to quote the 
> exact title of 
> > the document being cited.
> > 
> > cause uncertainty or ambiguity and so is exempt from the 
> usual acronym 
> > http://www.rfc-editor.org/policy.html#policy.abbrevs, but several 
> > recent RFCs using the acronym "MIB" have appeared without it being 
> > expanded anywhere.  RFC 4181 and RFC 4663 are examples.
> > 
> >> The draft should be divided into pages, none of which 
> should exceed 
> >> 58 lines.
> > 
> > like to let the RFC Editor take care of that (which they 
> will do anyway) ...

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Tue, 13 Feb 2007 14:16:06 -0500

On Monday, February 12, 2007 10:26:13 AM -0800 "C. M. Heard" 
<[email-masked]> wrote:

> I disagree with this comment -- I believe that doing as it suggests would
> make the title unnecessarily long.  Note that the Abstract already spells
> out the full title of RFC 4181.

A document title should be meaningful enough that by reading a citation or 
an rfc-index entry, you can tell what the document is about, at least at a 
high level.  Normally, I'd say that means _not_ naming an updated document 
only by its RFC number, since that effectively forms a citation within a 
citation that can be more work to track down than it should be.

In this case, I think the essential part is there -- it's an update to 
recognize the IETF Trust.  The last document of this type that I reviewed 
was RFC4748, and its title is constructed in exactly the same way.  I 
didn't have a problem with it then, and I don't now, either.

>> Acronyms (e.g., MIB) should be expanded on their first use.

I have to agree fully with Mike here - "MIB" is a well-known acronym; in 
fact, I'd argue that it's so well-known that more people know what it means 
than know what it stands for.

-- Jeff

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 15 Feb 2007 11:23:07 +0100

On 2007-02-13 20:16, Jeffrey Hutzelman wrote:
> A document title should be meaningful enough that by reading a citation 
> or an rfc-index entry, you can tell what the document is about, at least 
> at a high level.  Normally, I'd say that means _not_ naming an updated 
> document only by its RFC number, since that effectively forms a citation 
> within a citation that can be more work to track down than it should be.
> 
> recognize the IETF Trust.  The last document of this type that I 
> reviewed was RFC4748, and its title is constructed in exactly the same 
> way.  I didn't have a problem with it then, and I don't now, either.
> 
> 
> fact, I'd argue that it's so well-known that more people know what it 
> means than know what it stands for.
> 
> 
> -- Jeff

Yeah. I'm going no-objection on this one (but in general,
for more substantive documents, I agree with Gonzalo's points).

      Brian

---

From: "C. M. Heard" <[email-masked]>
Date: Tue, 20 Feb 2007 20:27:04 -0800 (PST)

Hi,

>>  didn't have a problem with it then, and I don't now, either.

As noted above, the title that drew the review complaint was constructed in
exactly the same way as that of draft-ietf-ipr-ietf-trust-update.  There
was no complaint about the title in the gen-art review of that document; see

http://www1.ietf.org/mail-archive/web/gen-art/current/msg01222.html
http://www1.ietf.org/mail-archive/web/gen-art/current/msg01223.html

and the title was left as-is in the published RFC (4748).

> for more substantive documents, I agree with Gonzalo's points).

There was no complaint about the use of 'MIB' without expansion in the
gen-art review of draft-harrington-8021-mib-transition -- see
http://www1.ietf.org/mail-archive/web/gen-art/current/msg00734.html --
and it was not expanded in the published RFC (4663) either.

It seems to me that an author should be able to expect that a practice
would be considered OK if it had been allowed in the gen-art review of
a previous Internet-Draft and had also been allowed by the RFC Editor in
the corresponding published RFC.

//cmh

---

From: Gonzalo Camarillo <[email-masked]>
Date: Wed, 21 Feb 2007 09:03:28 +0200

Hi,

yes, having a few guidelines on common issues would be useful.

Cheers,

Gonzalo

C. M. Heard wrote:
>>> > >  I disagree with this comment -- I believe that doing as it 
>>> suggests >  would make the title unnecessarily long.  Note that the 
>>> Abstract
>>> reviewed

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 21 Feb 2007 10:14:40 +0100

> yes, having a few guidelines on common issues would be useful.

So, that's in your hands! Suggest specific text or updates for
http://www.alvestrand.no/ietf/gen/art/review-guidelines.html

    Brian
> Gonzalo

<snip>

---

From: Scott W Brim <[email-masked]>
Date: Wed, 21 Feb 2007 09:25:00 -0500

>> the corresponding published RFC.

Clearly you want consistency with rfc-editor, and we are all trying to
learn how to do reviews from each other.  However, I would not require
consistency as a strong rule.  I think we are still going to be
creating the review process for a few more years.  The courts, and
gen-art, should be allowed to reconsider and even reverse decisions as
wisdom is gained and cultures change.