Subject: Re: Strawman - No more questions (Was: DRAFT Revision to the WG Document Writeup)

From: Joe Touch <[email-masked]>
Date: Tue, 01 Nov 2011 14:17:04 -0700

-1

While I appreciate the goal of extracting more information from the 
document shepherds, the new format makes it harder to scan the report 
and see if there are issues.

The assumption should be:

	N/A	if the issue is not applicable

	NO 	if the issue has nothing notable to report

	YES *and* some detail
		if the issue has something notable to report

I don't need detail if the answer is NO or N/A.

I don't need a full sentence in either of those cases vs. a simple NO or 
N/A.

Joe

On 10/30/2011 2:21 AM, Jari Arkko wrote:
> I have to say I like Pete's formulation more than the current one. But I
> also agree with Glen; it might be that instead of a "Yes" you will get
> "There is solid consensus" or "There are no concerns". Or my personal
> favorite, "Now that I run idnits checker there are some issues but we
> are sending it to the IESG anyway" :-)
>
> (And +1 to John on reviewing writeups like this in the wider community
> as well. But otherwise I would not take too much stress on this issue,
> these are all non-normative in any case.)
>
> Jari

---

From: Olafur Gudmundsson <[email-masked]>
Date: Wed, 02 Nov 2011 09:12:05 -0400

I was about to send to the list a long message with all kinds of nits 
and pointing out the stupidities of the wording in the list that Russ 
sent out.
Pete's prose does away with most of my objections and I hope his prose 
becomes the text we work from.

On 10/29/2011 8:15 PM, Pete Resnick wrote:
> On 10/27/11 2:45 PM, Paul Hoffman wrote:
>> On Oct 27, 2011, at 11:13 AM, Al Morton wrote:
>>
>>> With all the compound questions, I'm also beginning to wonder
>>> if a web-based form would save time for any busy chairs.
>>
>> +1. Or, at least, one question per bullet number. I find it odd to
>> respond to some of the questions with "Yes; yes; no" while others I
>> say just "Yes" because the rest of the compound is only needed if the
>> first is a "no".
>
> I privately wrote to Paul, only half jokingly, that if you're answering
> "Yes; yes; no", your probably doing this wrong. I've been giving my
> shepherds a harder time about writeups because yes/no answers don't help
> me all that much, and they certainly don't help the other ADs who might
> go read the writeup if they haven't been following the WG and have no
> context. I think the problem is putting these things in the form of a
> question doesn't get the right outcome.
>
> Below is a strawman complete rewrite of the document writeup template.
> Please tell me if you think I'm full of it, or if this is worth
> pursuing. I think the changes currently proposed should go ahead,
> whether or not folks think this is the bees-knees, because this will
> take more time to discuss than the simple changes proposed.
>
> Let me know what you think.
>
> Document Writeup:
>
> (1) Describe the review of this document done by the Document Shepherd
> and indicate whether this version of the document is ready for
> forwarding to the IESG for publication.

As phrased before IMHO this was a nonsensical request, this rewording at 
least tries get a DS to describe the process the document has got.
I still think "indicate whether this version.. is ready" is nonsensical
why send a request if the document is not ready ?

My rewording of this question:
    (1) Describe the review of this document performed by the Document
    Shepherd. If this version of the document is NOT ready for
    publication, justify why the document is forwarded to the IESG.

I.e. the reason might be to get broader review but the DS should justify 
why that could not be accomplished by going directly to some other 
group/area.

>
> (2) Describe the depth and the breadth of review that this document has
> had, both from key WG members and key non-WG members.
>
Nit: how is DS supposed to know if someone is a "key ????" ?
reason: just because someone makes lots of postings on a mailing list 
does not make him/her automatically a key member. Some of the people I 
listen most closely to only post a little but every post is thoughtful.

> (10) List other RFCs that this document obsoletes, and indicate whether
> they appear in both the title page header as well as in the Abstract and
> Introduction. List separately any RFCs that this document is requesting
> are to be moved to Historic, and indicate whether that request appears
> in the Introduction.
>

I like this wording

> (11) List other RFCs that this document updates, and indicate whether
> they appear in both the title page header as well as in the Abstract and
> Introduction.
>
> (12) Describe the Document Shepherd's review of the IANA considerations
> section, especially with regard to its consistency with the body of the
> document. List any protocol extensions that the document makes where the
> appropriate reservations in IANA registries have *not* been requested,
> or where the registries have *not* been clearly identified. List any
> concerns the Document Shepherd has regarding newly created IANA
> registries (e.g., initial contents for the registry that the document
> has *not* specified, or any allocations procedures for future
> registrations that the document has *not* defined, or an unreasonable
> name for the new registry; see [RFC5226]). List any Experts that the
> IESG will need to appoint during IESG Evaluation for any new Expert
> Review processes the document describes.
>

One of the issues that people do not think about when updating IANA 
registries when updating registrations is should the reference list
include new document only OR both old and new document.

Personally I like to include both for historical record.

> (13) Describe reviews and automated checking done by the Document
> Shepherd to validate sections of the document written in a formal
> language, such as XML code, BNF rules, MIB definitions, etc.
>
> (14) The IESG approval announcement includes a Document Announcement
> Write-Up. Please provide such a Document Announcement Write-Up. Recent
> examples can be found in the "Action" announcements for approved
> documents. Please fill in the sections of the below approval
> announcement, replacing the description in parentheses with appropriate
> text.
>

Nit: I when reading proto statements always skip first to the sections 
below before reading the answers above.
Does anyone else?
Does it make sense to move the Summaries to be before the questions ?

Actually I would reorder this to:
Document title:
Personnel:
Technical Summary:
Working Group Summary:
Document Quality:

Questions...
> Technical Summary
>
> (Relevant content can frequently be found in the abstract and/or
> introduction of the document. If not, this may be an indication that
> there are deficiencies in the abstract or introduction.)
>
> Working Group Summary
>
> (This should contain a description of anything in WG process that is
> worth noting. For example, describe controversies about particular
> points or decisions where the consensus was particularly rough.)
>
> Document Quality
>
> (This should contain a description of any existing implementations of
> the protocol. Indicate how many vendors have indicated their plans to
> implement the specification. List any reviewers that merit special
> mentions as having done a thorough review, e.g., one that resulted in
> important changes or a conclusion that the document had no substantive
> issues. Describe briefly the course of any MIB Doctor, Media Type, or
> other expert review that was done. Indicate the dates that any Media
> Type reviews were posted to the ietf-types list.)
>
> Personnel
>
> The Document Shepherd is (Name) (email address)
> The Responsible Area Director is (Name) (email address)
>

	Olafur

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Wed, 02 Nov 2011 13:09:11 -0400

On Sat, 2011-10-29 at 17:10 -0400, Russ Housley wrote:
> Keith:
> 
> Most of the time, the automated tools do the right thing, but there are corner cases to worry about.  I especially worry when a working group adopts an individual draft and does not change the name.  Another corner case involves a disclosure being submitted agains the I-D when it is an individual submission, and the I-D gets renamed when the WG accepts it, but the "replaced by' relationship not being entered into the the datatracker. 
> 
> To cover these admittedly rare cases, how about:
> 
>   (5) Has an IPR disclosure related to this document been filed?
>       If so, confirm that this disclosure shared with the WG. Was
>       there any discussion regarding the IPR disclosure? If so,
>       please summarize the discussion and the WG consensus.

I'm concerned that this question asks me, as a chair, to do some kind of
search and then _make a claim_ as to whether there are any IPR
disclosures relating to this document.  That worries me a lot, not only
because it requires more work, but because it requires me to somehow
know not what IPR claims have been brought to the working group but
which of thousands of IPR disclosures filed with the IETF might be
relevant to any particular document.

Personally, I think that's completely upside-down.  Anyone filing an IPR
disclosure with the IETF needs to clearly identify which documents
and/or proposals the disclosure is relevant to and bring it to the
attention of the responsible working group, or they haven't met the
disclosure requirement!

-- Jeff

---

From: Spencer Dawkins <[email-masked]>
Date: Wed, 02 Nov 2011 20:30:39 -0500

Hi, Jeffrey,

> attention of the responsible working group, or they haven't met the

Would it help to say "has an IPR disclosure been filed referencing this 
document?"

Spencer

---

From: Paul Hoffman <[email-masked]>
Date: Wed, 2 Nov 2011 19:09:33 -0700

On Nov 2, 2011, at 6:30 PM, Spencer Dawkins wrote:
> Would it help to say "has an IPR disclosure been filed referencing this document?"

It would help me for it to say that. It is easily checked and doesn't involve interpretation.

--Paul Hoffman

---

From: Al Morton <[email-masked]>
Date: Thu, 03 Nov 2011 03:25:30 -0400

At 10:09 PM 11/2/2011, Paul Hoffman wrote:
>...

+1, nicely done.
Al

---

From: "James M. Polk" <[email-masked]>
Date: Thu, 03 Nov 2011 13:04:28 -0500

>>doesn't involve interpretation.

ok - I like this too.

James

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Thu, 03 Nov 2011 14:52:05 -0400

> It would help me for it to say that. It is easily checked and doesn't involve interpretation.

Agreed

---

From: Linda Dunbar <[email-masked]>
Date: Mon, 07 Nov 2011 23:07:40 +0000

Totally agree with Jeff's concern. 

Linda Dunbar

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On
> Behalf Of Jeffrey Hutzelman
> Sent: Wednesday, November 02, 2011 12:09 PM
> To: Russ Housley
> Cc: IETF WG Chairs; [email-masked]
> Subject: Re: DRAFT Revision to the WG Document Writeup
> 
> > Most of the time, the automated tools do the right thing, but there
> are corner cases to worry about.  I especially worry when a working
> group adopts an individual draft and does not change the name.  Another
> corner case involves a disclosure being submitted agains the I-D when
> it is an individual submission, and the I-D gets renamed when the WG
> accepts it, but the "replaced by' relationship not being entered into
> the the datatracker.
> >

---

From: Spencer Dawkins <[email-masked]>
Date: Mon, 14 Nov 2011 04:53:21 -0600

>> accepts it, but the "replaced by' relationship not being entered into

I know that Steve Coya was very proud of the face that draft names 
didn't have to change when working groups adopted drafts, when he was 
doing the working group chair training in the late 1990s. But that was a 
long time ago.

If this flexibility is getting in the way (and one might reasonably 
argue that it already gets in the way for other reasons, because people 
assume draft names mean something even though that's just a convention), 
we could solve this problem, and probably some others, by renaming all 
the drafts when they are adopted.

Perhaps this is an idea whose time has come.

Spencer

---

From: Glen Zorn <[email-masked]>
Date: Sun, 20 Nov 2011 14:10:22 +0800

On 11/14/2011 6:53 PM, Spencer Dawkins wrote:

...

> Perhaps this is an idea whose time has come.

I think so.

---

From: Cullen Jennings <[email-masked]>
Date: Thu, 24 Nov 2011 06:25:53 -0700

Along theses lines ... I would prefer most of the questions to have answers of the form 

N/A
NO
YES
ITS COMPLICATED - talk to me or follow the WG or perhaps some more explanation

My experience on IESG was shepherds spent a huge amount of time doing write-ups which were mostly did not contain information the IESG needed to be aware of that was not already known. Asking people to run nits or check a grammar does cause checks to get done.

On Oct 31, 2011, at 7:48 AM, Andrew Sullivan wrote:

> On Sat, Oct 29, 2011 at 07:15:06PM -0500, Pete Resnick wrote:
> [&c.]
> I like it, though the subsequent discussions of the essay questions
> puts me in mind of the aphorism, "I didn't have time to write a short
> letter, so I've written a long one instead."  I hope the ADs know what
> they're asking.
> 
> A
> 
> -- 
> Andrew Sullivan
> [email-masked]
>