Subject: Re: Call for review of proposed update to ID-Checklist

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Sat, 9 Aug 2008 17:40:58 +0200

I have started to updatre the document based on feedback.

My approach is to clearly make those changes that are straight forward,
simple end editorial. 

For other changes, I need to hear (I guess from Russ) that there
is consensus to make such a change.

It may take a little more time before I have checked and evaluated
all comments.

Inline
> ----- Original Message ----- 
> From: "Frank Ellermann" <[email-masked]>
> To: <[email-masked]>
> Sent: Wednesday, July 09, 2008 8:51 AM
> Subject: Re: Call for review of proposed update to ID-Checklist
> 
> 
> Re: Call for review of proposed update to ID-ChecklistIETF Chair wrote: 
> 
>> http://www.ietf.org/Draft-ID-Checklist.html 
> 
> Nits:  
> (1) Archive older versions in a plain text format as for 
>    I-Ds (for use with various IETF tools working on I-Ds) 

I can generate I-Ds if that helps. I can even submit those.
Russ, do you want me to do that?

> (2) s/2434/5226/ 
> (3) s/2780/2780 + 5237/ 

above 2 are done in my new copy

> (4) I-D.bellovin expired months ago with three DISCUSSes, 
>    please resolve that by time-out ABSTAINs (or similar) 

There is a new rev dated Aug 03 2008.
That will now get picked up by the xml2rfc tool.
I will not comment on the time-out on ABSTAINs, that is an IESG
issue, not one that relates to teh ID-Checklist document.

> (5) s/4181/4181 + 4841/ 
> (6) s/4234/5234/ 

The above 2 have been updated in new copy

> (7) Please add RFC 5137 (BCP 137) to section 4 as item 5 

I do not feel confident to add that unless Russ tells me that this is
consensus and should be added.

> (8) I-D.2223bis expired 3.5 years ago, and is flagged as 
>    DEAD since May 2008 
> 

I know. I have communicated with Russ and RFC-Editor about this.
We will replace it with a reference to 
     http://www.rfc-editor.org/rfc-style-guide/rfc-style-manual-08.txt

Bert
Editor of ID-Checklist

> Frank 

_______________________________________________
Ietf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/ietf

---

From: Dave Crocker <[email-masked]>
Date: Sat, 09 Aug 2008 09:20:48 -0700

> is consensus to make such a change.

Bert, et al,

Something that might help further discussions quite a bit is considering 
annotation and re-organization of the document, to clarify some basic 
distinctions.

For example, labeling the bits that are based on IETF standards rules versus the 
bits that are based on IESG requirements?  Equally, what pertains to 
documentation standards versus what pertains to technical/protocol issues?  The 
document has evolved into a possibly disorganized mixture of these and last 
month's discussions was challenged to separate issues, I think.

This kind of change would not be modification of the Checklist semantics, but 
would add clarity to what is currently there.

Any serious effort to clarify the document in this way is likely to engender 
more focused discussion than was possibly earlier, if only by offering some 
specific and relevant categorical distinctions.

That discussion is then more likely to produce the kind of input that will help 
Russ make those consensus assessments.

d/

-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net
_______________________________________________
Ietf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/ietf

---

From: John C Klensin <[email-masked]>
Date: Sat, 09 Aug 2008 14:30:16 -0400

Bert,

I want to reinforce Dave's comments and perhaps carry them a bit
further.  If the ID-checklist were just the general guidance
that I believe it started out to be, the distinctions I suggest
below would probably be unnecessary.  But we've seen recently
that there are very few steps between having a list and having
everything on that list become rigid, mechanically-applied,
requirements.

--On Saturday, 09 August, 2008 09:20 -0700 Dave Crocker
<[email-masked]> wrote:

> Bert, et al,
> 
> Something that might help further discussions quite a bit is
> considering annotation and re-organization of the document, to
> clarify some basic distinctions.
> 
> For example, labeling the bits that are based on IETF
> standards rules versus the bits that are based on IESG
> requirements?  Equally, what pertains to documentation
> standards versus what pertains to technical/protocol issues?

Many of the bits that "pertain to documentation requirements"
are IESG interpretations of RFC Editor guidelines.  The RFC
Editor has traditionally been much more flexible about their
rules than recent trends in the IESG have been.  Even when the
rules come from the IESG, it would be useful to better
distinguish between firm requirements (e.g., the IPR
boilerplate) and guidance (e.g., things to which one should
either conform or expect to have to explain, convincingly, why
not).

> The document has evolved into a possibly disorganized mixture
> of these and last month's discussions was challenged to
> separate issues, I think.
> 
> This kind of change would not be modification of the Checklist
> semantics, but would add clarity to what is currently there.

But it is precisely the semantics that I think are at issue.
This is less what is in the checklist because I believe we could
agree that everything there is at least good general guidance
than about the apparent tendency for entries in the checklist to
become rigid rules that will be enforced even if specific
circumstances suggest otherwise.

> Any serious effort to clarify the document in this way is
> likely to engender more focused discussion than was possibly
> earlier, if only by offering some specific and relevant
> categorical distinctions.

And, in the case of the distinctions I'm suggesting, permit
meaningful community consideration of whether there is consensus
about particular rules, which may be different from consensus
about general guidance.

regards,
     john

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Sat, 9 Aug 2008 20:52:32 +0200

John and Dave,

I think that both of you (and some others) arwe looking at the ID_Checklist
too much as if it is part of our (rigid) process. Our processes aredescribed
in formally approved BCP documents.

The ID-Checklist is intended (or at least that is how it started, and as far
as I am concerned that is still the intention) to help in a few areas:

- Make document authors/editors and WG chairs (and reviewers) aware
  of the many little things we found as ADs and IESG when reviewing
  documents that came out of WGs. Those mistakes always later caused
  confusion and delay in the further process.
- Reduce the document-time of AD, IESG, IETF LC-reviewers, RFC-Editor by
  reducing extra steps to fix little and simple things.
- All those simple things were (and still are) documented in other RFCs or
  in the RFC-Editor Style manual, and so it is/was not a new set of
  rules or requirements
- Authors/Editors SHOULD know all these little things, but they often
  did/do not know exactly what they are or where to find them.
  The ID_Checklist is intended to help find these things.
- By documenting these things, it became easier/quicker to point to them
  (both if found at AD or IESG review and earlier)
- By documenting them, the WG-Chair (document shepherd) can do a lot
  of these checks, so that they can not slip through later in the process
  or delay the process afetr IESG approves.
- I believe that the ID-Checklist also helped Henrik write the id-nits tool 
that
  will do a check for most of the checlist items that can (reasonably) be
  checked by software

I remember that before we had the ID-Checklist, we often wasted a lot of 
time
on this simple things (be it by taking a DISCUSS, by interacting with the 
authors,
by adding RFC-Editor notes, By later checking if things were fixed, By later
discussing aith editors/authos why such little fixes were made etc etc ect).

So I believe it has served its purpose very well.
And I also believe that the intended purpose is still served very well with 
the
current version, albeit that some clarifications an dupdates to ptrs and
citations/references are in order.

Pls do not consider this ID-Checklist as part of our BCP approved process
documents. That is not the intention of it and I think it would be bad to
try and make it part of our set of BCPs that describe our (IETF) process.

So I am not prepared yet to take on a massige reorg and as a result
probably a long discussion and wordtsmitting effort.

If Russ (or the IESG) tells me that they DO want a complete re-org I will
re-consider. But that was/is not the task I was asked to do (I believe).

I hope you understand

Bert
Editor of the ID_Checklist.

---

From: John C Klensin <[email-masked]>
Date: Sat, 09 Aug 2008 15:58:03 -0400

--On Saturday, 09 August, 2008 20:52 +0200 "Bert Wijnen

Bert,

We are in complete and utter agreement with each other about the
appropriate role of the ID_Checklist.  For better or worse, the
IESG apparently does not agree, as evidenced most recently in
their response to my appeal about turning a suggestion from the
original version of the Checklist into a firm rule without
having that explicitly confirmed by the community.

We also agree that revising the Checklist into a document that
is suitable for use as part of a package of firm rules is a
rather different job than updating it while being consistent
with its original purpose.

So I withdraw my suggestion and comments but strongly suggest
that you make sure that your intentions for the document and
those of the IESG are in synch before proceeding much further.

regards,
    john

---

From: "Frank Ellermann" <[email-masked]>
Date: Sat, 9 Aug 2008 22:28:45 +0200

Bert Wijnen wrote:

> I believe that the ID-Checklist also helped Henrik write the 
> id-nits tool that will do a check for most of the checlist
> items that can (reasonably) be checked by software
[...]

FWIW I consider your checklist as very helpful especially for
new authors, for all the reasons you have stated.

That things can get interesting when authors feel the need to
explore exceptions from a SHOULD is as it is, your checklist
can't go into all possible details.  The 2821bis case was one
of those interesting things, we could talk about it for hours,
but this doesn't belong into the checklist.

New authors hopefully know that not following a SHOULD needs
a good excuse, and other authors certainly know it, but might
still disagree about some details of "good enough" excuses.

RFCs that will be so popular that everybody and his dog will
take their clues from these RFCs and not a relatively obscure
IETF-internal checklist are rare.   

I've proposed to add RFC 5137, but if you or Russ think that
this is no good idea it is no problem.  John proposed some
tweaks, I hope you'll look at his proposals.

> I believe it has served its purpose very well.

Yes.  Of course it's overwhelming what potential authors will
find when they look for advice, but again I think that is as
it is, there can't be one authoritative rule saying it all...

For starters folks here would disagree about the "authority".

And it won't suprise anybody here when I admit that one major
point in the 2606bis drafts is to confirm RFC 2606 as it was,
a recommendation wrt examples.  Not more and not less.  

FWIW I could even provide an example where not following this
recommendation triggered a DISCUSS, later solved by a "good
excuse".  I'd not support to twist this 2606 recommendation
into mustard.

 Frank

---

From: Dave Crocker <[email-masked]>
Date: Sun, 10 Aug 2008 08:38:05 -0700

Bert Wijnen (IETF) wrote:
> too much as if it is part of our (rigid) process. Our processes 
> are described in formally approved BCP documents.

Bert,

I am trying to distinguish between what the Checklist "is intended to be" from 
the competing views of what it actually is, as discussed in this thread 8-11 
July.  That thread made clear that a variety of serious and thoughtful people 
have very different views on the actuality.

This sort of debate is never resolved by abstract exchanges. It needs hard data.

I think your previous note correctly listed what the document was (and probably 
is) *intended* to be.  I think the thread made clear there is a strong case that 
the document has become more than that. I think it also made clear that the 
basis for its becoming more is fuzzy.

So my suggestion is not seeking to directly resolve the matter, but rather to 
provide a tool for discussion.  Simply put, it adds an audit trail to the 
document's content that should help folks by providing some relatively objective 
information that makes clear what is and is not based on rules defined elsewhere.

Hence, I am hoping that detailed attention to John's note following-up my own 
suggestion comes later, since I read it as possibly seeking to resolve things 
directly. More probably, he was merely trying to help make the case for why the 
document needs substantiation of its particulars.

I suggested that you perform the audit exercise partly because you are the one 
modifying the document and partly because you are friendly to the document's 
current form.

d/
-- 

   Dave Crocker

---

From: Brian E Carpenter <[email-masked]>
Date: Mon, 11 Aug 2008 11:07:02 +1200

> those of the IESG are in synch before proceeding much further.

I'd like to say that both as an author and as a reviewer, I have
always found both the ID checklist and the IDnits checker to be
of immense pragmatic value. Obviously, if the checklist or the
checker complains about something that isn't obviously a bug,
the author, shepherd, AD or reviewer will have to enter "think"
mode or even "negotiate" mode. I agree that it's a good idea
to be clear about that.

    Brian

---

From: John C Klensin <[email-masked]>
Date: Sun, 10 Aug 2008 19:52:24 -0400

--On Monday, August 11, 2008 11:07 AM +1200 Brian E Carpenter 
<[email-masked]> wrote:

> I'd like to say that both as an author and as a reviewer, I
> have always found both the ID checklist and the IDnits checker
> to be of immense pragmatic value.

I agree.   I've just had a painful recent experience (not the 
first one) in which some overzealous person has assumed that 
some provision of one or the other is actually a firm rule and 
proceeded to try to enforce it in some draconian fashion.  I 
don't believe that is wise, appropriate, or healthy.   So I'm 
trying to be sure that the Checklist is clear about both its 
overall intent and the strength of any guidelines it presents in 
the hope of preventing that sort of behavior in the future.

> Obviously, if the checklist
> or the checker complains about something that isn't obviously
> a bug, the author, shepherd, AD or reviewer will have to enter
> "think" mode or even "negotiate" mode. I agree that it's a
> good idea to be clear about that.

Either "think" mode or "negotiate" mode would be a considerable 
improvement over what has appeared to be "this is a rule, it is 
immutable, change your document".

     john

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Mon, 11 Aug 2008 10:24:35 +0200

> mode or even "negotiate" mode. I agree that it's a good idea

I am checking with the IESG if they also agree with that

Bert
Editor for the ID_Checklist

---

From: SM <[email-masked]>
Date: Mon, 11 Aug 2008 10:42:09 -0700

>in formally approved BCP documents.

[snip]

>try and make it part of our set of BCPs that describe our (IETF) process.

The IESG pointed to the ID-Checklist in its response to an 
appeal.  If the intention is not to have the ID-Checklist as part of 
the approved process documents, it shouldn't be used as a formally 
approved document.

Regards,
-sm

---

From: Russ Housley <[email-masked]>
Date: Tue, 12 Aug 2008 10:28:33 -0400

I am working on a solution for this with the Secretariat.  It is one 
aspect of the web site redesign project.  I do not think that an 
Internet-Draft is needed.

Russ

At 11:40 AM 8/9/2008, Bert Wijnen \(IETF\) wrote:
>>(1) Archive older versions in a plain text format as for    I-Ds 
>>(for use with various IETF tools working on I-Ds)
>

---

From: "Frank Ellermann" <[email-masked]>
Date: Wed, 13 Aug 2008 02:25:23 +0200

Russ Housley wrote:
 
> I do not think that an Internet-Draft is needed.

The source is already a variant of xml2rfc input, from
there it's easy to arrive at plain text output for the
ordinary diff tools.  

Adding version numbers for archiving working with the
diff tool could be as simple as "use name-NN.txt for
version NN".

 Frank