Subject: [proto-team] revision of draft-ietf-proto-wgchair-doc-shepherding attached

From: Lars Eggert <[email-masked]>
Date: Wed, 7 Jun 2006 15:01:25 +0200

Hi,

please find the text and XML version of my edits to draft-ietf-proto- 
wgchair-doc-shepherding-06 below. I'm also including an rfcdiff of  
the changes in HTML format.

Comments?

Lars

-- 
Lars Eggert                                     NEC Network Laboratories

_______________________________________________
proto-team mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/proto-team

---

From: David Meyer <[email-masked]>
Date: Wed, 7 Jun 2006 07:09:52 -0700

> the changes in HTML format.

	Sorry about the delay in responding. First, thanks for
	doing the work. The document has been sort of ideal since
	Allison updated it. Second, I like your changes, so no
	substantive problems here. 

	Thanks again,

	--dmm

---

From: Lars Eggert <[email-masked]>
Date: Thu, 8 Jun 2006 14:02:50 +0200

Hi,

> 	substantive problems here.

thanks for the feedback! What does the rest of the team think?

Find a small update below that fixes some wording and grammar nits only.

Lars

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 08 Jun 2006 21:25:42 +0200

Hi Lars,

You've put quite a bit of work into this, I see.  Overall I like it,
but I have one major disagreement:

        I'm not especially thrilled with the elevation of "PROTO" from
        something associated with the PROTO team to a term specifically
        for this process improvement.  The previous version of the
        document didn't go as far as this goes, and I'd rather see us
        move from reference to the 'PROTO' process to simply 'the
        Shepherding process' or 'the Document Shepherding process'.
	
	In line with this, I'd propose to change any reference to
	PROTO Write-Up to 'Document Shepherd Write-Up' throughout the
	document.

Lesser comments:

INTRODUCTION, paragraph 14:

>    This document describes methodologies that have been designed to
>    improve and facilitate IETF document flow processing.  It specifies a
>    set of procedures under which a working group chair or secretary
>    serves as the primary Document Shepherd for a document that has been
>    submitted to the IESG for publication.  Before this, the shepherding
>    role has traditionally been filled by the Responsible Area Director
>    for the working group.

        s/Responsible Area Director/Area Director responsible/

INTRODUCTION, paragraph 19:

>    In summary, a Document Shepherd continues to care for a shepherded
>    document during its post-WG lifetime similar to how how he or she has
>    done while responsible for the document in a working group.

        s/how how/the way/
        s/done while/cared for it while/

Section 1., paragraph 1:

>    Early in 2004, the IESG undertook several experiments aimed at
>    evaluating whether any of the proposed changes to the IETF document
>    flow process would yield qualitative improvements in document
>    throughput and quality.  One such experiment, referred to as the
>    "PROTO process" or "PROTO" (because it was created by the "PROcess
>    and TOols" or PROTO [PROTO] team, is a set of methodologies designed
>    to involve working group chairs or secretaries more directly in their
>    documents' approval life cycle.  In particular, the PROTO team
>    focused on improvements to that part of a document's life cycle that
>    occurs after the working group and document editor have forwarded it
>    to the IESG for publication.

        s/improvements to that part/imrovements to the part/

Section 3.3., paragraph 10:

>    (3.e)  The Document Shepherd then communicates the DISCUSS and
>           COMMENT items to the document authors, the working group.

        s/authors, the working group/authors and the working group/

Section 3.3., paragraph 19:

>    (3.i)  The Responsible Area Director moves document to the "Approved
>           - Announcement to be sent" state in the ID Tracker, or, if he
>           or she deems the changes to the revised document significant,
>           issues a new WG last call.  In the latter case, the document
>           may go through a full IESG Evaluation process again.

        Is it really the AD that issues the new WG last call??

Regards,

	Henrik

---

From: Lars Eggert <[email-masked]>
Date: Fri, 9 Jun 2006 09:15:15 +0200

Hi,

>         Shepherding process' or 'the Document Shepherding process'.

I didn't make that change - that has been there for a while (see the  
abstracts of -06 and -05). I'm completely fine with changing to one  
of your proposed terms.

> 	PROTO Write-Up to 'Document Shepherd Write-Up' throughout the

Also OK.

> Lesser comments:

Agree with all of them, will make the edits.

Lars

---

From: Lars Eggert <[email-masked]>
Date: Fri, 9 Jun 2006 15:09:22 +0200

> Agree with all of them, will make the edits.

Revision with Henrik's suggestions attached.

Lars

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 09 Jun 2006 16:28:39 +0200

Hi Lars,

  I'm of course biased, having suggested the changes, but I find that
to me it seems that the document reads much more smoothly now.  Maybe
that's the reason why I found more stuff...

> Revision with Henrik's suggestions attached.

Minor fix:

Section 3.1, paragraph 7:

>    (1.d)  Does the Document Shepherd have any specific concerns or
>           issues with this document that the Responsible Area Director
>           and/or the IESG should be aware of?  For example, perhaps you
>           he or she is uncomfortable with certain parts of the document,
>           or has concerns whether there really is a need for it.  In any
>           event, if those issues have been discussed in the WG and the
>           WG has indicated that it still wishes to advance the document,
>           detail those concerns here.

	s/perhaps you he or she/perhaps he or she/

Larger issue:

Section 3.1, paragraph 11:

>    (1.i)  For Standards Track and BCP documents, the IESG approval
>           announcement includes a write-up.  Please provide such a
>           write-up.  Recent examples can be found in the "Action"
>           announcements for approved documents.  The approval
>           announcement contains the following sections:

One question for clarification: In the current revision, the "Document
Shepherd Write-up" seems to be defined as what's covered under 1.i, and
presumably the "Document Shepherd Questionnaire" is the whole of the
(1.a)..(1.i) set of questions.  It seems to me that in some places the
document mentions the Document Shepherd Write-up where intention is to
talk about talk about both questionaire and (1.i) write-up; for instance
here:

>    The Document Shepherd MUST send the Document Shepherd Write-Up to the
>    Responsible Area Director and [email-masked] together with
>    the request to publish the document.  The Document Shepherd SHOULD
>    also send the write-up, minus any discussion of possible appeals, to
>    the working group mailing list.

I seem to remember that during the original discussions, we sometimes
(mostly?) referred to the whole questionnaire as the write-up.  Whatever
we call them, it would be good to have clear and separate terms for the
(1.i) writeup and for the questionnaire, and make sure that where the
document now mentions the write-up, it is verified (and if needed corrected)
so it correctly indicates (1.i) write-up or questionnaire.  It may be that
most places where the document now mentions 'Write-up' the whole
questionnaire is meant - if we define the 'Write-up' as being the whole
questionnaire, we should have a different term for the (1.i) write-up.

Regards,

	Henrik

---

From: Lars Eggert <[email-masked]>
Date: Fri, 9 Jun 2006 16:55:27 +0200

Hi,

> that's the reason why I found more stuff...

No problem.

> 	s/perhaps you he or she/perhaps he or she/

OK

> talk about talk about both questionaire and (1.i) write-up;

Actually, I tried to remove the distinction between write-up and  
questionnaire, because the terms weren't used consistently, and just  
call the whole set of questions write-up.

I missed two instances of the term questionnaire. If I change those  
to write-up, will this be OK? Or do you want to go through the  
document and look at all places where the write-up is mentioned and  
check which term should be used?

Lars

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 09 Jun 2006 17:35:44 +0200

Hi Lars,

> call the whole set of questions write-up.

Aha.  That works very well for me, but then there's some corrections
needed.  I'll make a text proposal.

> check which term should be used?

I'll go through the document.  Maybe not with a fine-toothed comb, but
enough to suggest appropriate changes, I hope.

Regards,

	Henrik

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 09 Jun 2006 17:48:29 +0200

Hi again,

on 2006-06-09 17:35 Henrik Levkowetz said the following:
[Lars]
> enough to suggest appropriate changes, I hope.

It seems to me that the two instances of questionnaire are OK.  But I
believe the following paragraphs should be fixed.  Possible proposals
inline:

Section 3.1, paragraph 3:

>    The second part of the task is to prepare the Document Shepherd
>    Write-Up that is input to both the ballot for the IESG telechat and
>    to the eventual IETF-wide announcement message.  Item number (1.i)
>    describes the elements of this write-up.  Please see other protocol
>    announcements in the IETF Announce archive for examples of such
>    write-ups.

	s/Document Shepherd Write-Up that is/document summary that is/
	s/elements of this write-up/elements of this summary/
	s/such write-ups/such summaries/

>           announcement contains the following sections:

	s/write-up/document summary/g

Regards,

	Henrik

---

From: Lars Eggert <[email-masked]>
Date: Sun, 11 Jun 2006 17:32:29 +0200

Hi,

On Jun 9, 2006, at 17:48, Henrik Levkowetz wrote:
> believe the following paragraphs should be fixed.

this introduces a third term ("document summary") in addition to  
"questionnaire" and "write-up". Do you really think this is  
clarifying things?

Lars

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 12 Jun 2006 15:16:04 +0200

Hi Lars,

Since the "write-up" referred to in (1.i) is *not* the Document Shepherd
Write-up, I think it is more misleading to referring to it as 'the write-up'
in a section concerned with the Document Shepherd Write-up.  It is also
not the questionnaire.  If anything, we have "questionnaire" + "document
summary" == "Document Shepherd Write-up".

Since we are talking about 3 different things, 3 different terms is, I
think, the best way to go.  So yes, I was hoping this would be clearer.

Regards,

	Henrik

on 2006-06-11 17:32 Lars Eggert said the following:
> ------------------------------------------------------------------------
>

---

From: Lars Eggert <[email-masked]>
Date: Mon, 12 Jun 2006 16:23:45 +0300

> summary" == "Document Shepherd Write-up".

Oops - you're right. I think I placed that piece of text somewhere  
else in my mental map of the document.

I'll make the change but not email another version just yet - maybe  
there are other comments?

Lars