Subject: Document shepherd role

From: Benoit Claise <[email-masked]>
Date: Mon, 22 Apr 2013 09:08:10 +0200

IETF WG chairs,

We sent a similar message to the operations an management area chairs.
Therefore if you have seen the contents before, apologies, the resulting
IESG discussion has indicated that we should distribute it more widely.

During the last IETF meeting, the community discussed a lot about the
transport AD situation. One aspect of this is the time commitment for an
AD position!

During the last IETF meeting, the community discussed a lot about
diversity. All sort of diversities, including the IESG diversity. One
specific aspect is the diversity of IESG member affiliations.

Let me share my experience after one year of service as AD.
1. Yes, I like this job. I believe it makes a positive a difference for
the Internet (hopefully positive, you'll be the judges, but that's not
the point of this email )
2. Yes, this AD role requires (more than) a full time job if done
conscientiously.
3. I'm concerned that we slowly created a set of requirements for an
IESG position that will make difficult to find ADs in the future ...
except from big companies, or when dedicated funding is allocated. Not
good for diversity.
4. Believe it or not, one substantial part of my OPS activities is the
follow up on the open issues. Recently, for a single draft, I spent
hoouuurrrssss trying to track all the open issues from the directorates
and the IESG, and chasing the authors. On top of taking some time, I had
to be become expert for every single aspect of the specifications to
evaluate whether the answer was right. After all, I have to defend your
WG document during the IESG call.

Considering the discussion above, let me focus on one important role
within the community: the document shepherd.  This job, when done
according to RFC 4858 would free up a huge amount of time for the ADs,
and would speed up the document publication.

Please read RFC 4858, specifically
      3.2.  Document Shepherding during AD Evaluation  . . . . . . . .  9
      3.3.  Document Shepherding during IESG Evaluation  . . . . . . . 10

Bottom line, the document shepherd job doesn't stop when the write-up is
sent.
I would like the document shepherds to follow the RFC 4858 instructions.
Specifically concerning the follow up part.
That being said, the shepherd, chairs, and the WG participants together
are the custodians of WG output. So the obligations isn't solely
invested in the shepherds. Their role via the questionnaire
fundamentally is to document that the things required have been done,
and to manage the remainder of the process.

To come back to the first paragraph of my email, the document shepherd
job (let me stress again, when done according to the function described
in RFC 4858) would be beneficial for the entire community longer term.
Let me explain: if the AD job was not a full time job, it might be
easier to have diversity in the pool of AD candidates.

This message was sent to all OPS WG chairs, and is now being distributed
more widely.

Also, let's keep in mind that it's not a requirement that only WG chairs
are document shepherds. See
http://www.ietf.org/iesg/statement/document-shepherds.html,The Shepherds
role is a source of valuable insight into the later stages of the RFC
process and a stepping stone for competency in other IETF roles.

Regards, Benoit

---

From: "Howard, Lee" <[email-masked]>
Date: Mon, 22 Apr 2013 15:37:42 -0400

On 4/22/13 3:08 AM, "Benoit Claise" <[email-masked]> wrote:
...
>      3.3.  Document Shepherding during IESG Evaluation  . . . . . . . 10

...

>easier to have diversity in the pool of AD candidates.

Can we offer some recognition for Document Shepherds? I don't think they
even get listed in the Acknowledgments section, unless they have already
contributed.  Unlike Author, Contributor, WG Chair, AD, Directorate, and
Secretary, the Shepherd toils in anonymity.

Shepherding is good experience for a future WG chair.  It would be nice to
recognize the work in and of itself.

Lee

This E-mail and any of its attachments may contain Time Warner Cable proprietary information, which is privileged, confidential, or subject to copyright belonging to Time Warner Cable. This E-mail is intended solely for the use of the individual or entity to which it is addressed. If you are not the intended recipient of this E-mail, you are hereby notified that any dissemination, distribution, copying, or action taken in relation to the contents of and attachments to this E-mail is strictly prohibited and may be unlawful. If you have received this E-mail in error, please notify the sender immediately and permanently delete the original and any copy of this E-mail and any printout.

---

From: Peter Saint-Andre <[email-masked]>
Date: Mon, 22 Apr 2013 13:45:37 -0600

> Secretary, the Shepherd toils in anonymity.

Not always... :-)

http://tools.ietf.org/html/draft-saintandre-impp-call-info-02#appendix-A

This is something we can all do as document authors and WG chairs.

> recognize the work in and of itself.

+1

Peter

---

From: Benoit Claise <[email-masked]>
Date: Mon, 22 Apr 2013 22:09:55 +0200

>> recognize the work in and of itself.
That makes a lot of sense.
And I like the way Peter did it in the example above.

Regards, Benoit

---

From: Paul Kyzivat <[email-masked]>
Date: Mon, 22 Apr 2013 17:46:01 -0400

I found this discussion enlightening.

I'd like to add a slightly different, but related, suggestion:

Several times now when I have shepherded a draft, I start doing the 
writeup and realize it would have been really helpful to started on that 
writeup sooner - even before the document was ready for progression. My 
conclusion is that it would probably be good to assign a shepherd to a 
document as soon as it is adopted as a wg draft. (Assuming there is an 
intent that it become an RFC.) And then the shepherd can *start* filling 
out the template early. That way, after WGLC it won't take a lot of 
research, and a good memory, to fill in everything.

	Thanks,
	Paul

---

From: Margaret Wasserman <[email-masked]>
Date: Mon, 22 Apr 2013 17:54:33 -0400

In busy working groups, ones with a lot of documents, it isn't unusual for the chairs to divide up responsibility for the active WG drafts.  When those drafts go into the IESG, the WG chair who has been responsible for the document during the WG process usually shepherds the draft through the IESG.  That works pretty well, in my experience.

In less busy groups, ones with fewer drafts, the chairs may work together on all of the documents.  They then have to assign a shepherd at the end.  Depending on the roles of the individual chairs, this can work well, but sometimes the chair needs to fill in a lot of knowledge to do the shepherding task.  In these cases, I agree it might make sense to explicitly decide who will shepherd the draft earlier in the process.

Margaret

On Apr 22, 2013, at 5:46 PM, Paul Kyzivat <[email-masked]> wrote:

> Several times now when I have shepherded a draft, I start doing the writeup and realize it would have been really helpful to started on that writeup sooner - even before the document was ready for progression. My conclusion is that it would probably be good to assign a shepherd to a document as soon as it is adopted as a wg draft. (Assuming there is an intent that it become an RFC.) And then the shepherd can *start* filling out the template early. That way, after WGLC it won't take a lot of research, and a good memory, to fill in everything.
> 
> 	Thanks,
> 	Paul
>

---

From: Barry Leiba <[email-masked]>
Date: Mon, 22 Apr 2013 18:00:31 -0400

Gee, Paul, you've provided the perfect intro.   Please check out my
document, which I'm trying to figure out what to do with:
https://datatracker.ietf.org/doc/draft-leiba-extended-doc-shepherd/

Barry

On Monday, April 22, 2013, Paul Kyzivat wrote:

>> http://www.ietf.org/iesg/**statement/document-shepherds.**html,The<http://www.ietf.org/iesg/statement/document-shepherds.html,The>Shepherds

---

From: Paul Kyzivat <[email-masked]>
Date: Mon, 22 Apr 2013 18:04:49 -0400

> In less busy groups, ones with fewer drafts, the chairs may work together on all of the documents.  They then have to assign a shepherd at the end.  Depending on the roles of the individual chairs,…

In the groups I chair we haven't overtly considered who will shepherd a 
document until after WGLC. Maybe this isn't a problem for other groups. 
But for mine I'm just discovering that starting this earlier would be 
helpful.

	Thanks,
	Paul

---

From: Paul Kyzivat <[email-masked]>
Date: Mon, 22 Apr 2013 18:24:26 -0400

> https://datatracker.ietf.org/doc/draft-leiba-extended-doc-shepherd/

Perfect!

But I do think the writeup can usefully be started before WGLC.
It will then provide a place to keep useful information. For instance, 
if there is a lot of debate and controversy about some points, then info 
about that can be captured in the draft writeup while the memory of that 
is fresh. (Better than reading through months or years of email later to 
remember the details of that controversy.)

	Thanks,
	Paul

>     writeup and realize it would have been really helpful to started on
>     that writeup sooner - even before the document was ready for
>     progression. My conclusion is that it would probably be good to
>     assign a shepherd to a document as soon as it is adopted as a wg
>     draft. (Assuming there is an intent that it become an RFC.) And then
>     the shepherd can *start* filling out the template early. That way,
>     after WGLC it won't take a lot of research, and a good memory, to
>     fill in everything.
>
>              Thanks,
>              Paul
>
>         http://www.ietf.org/iesg/__statement/document-shepherds.__html,The
>         <http://www.ietf.org/iesg/statement/document-shepherds.html,The>
>         Shepherds

---

From: "Bernie Volz (volz)" <[email-masked]>
Date: Mon, 22 Apr 2013 22:31:01 +0000

I think before the WGLC is started or during the WGLC process, the shepherd (or WG chair) should really review the document as if doing the shepherd write -up (it makes the final write-up easy). I've used the process recently when doing WGLCs for DHC WG documents.

- Bernie

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Paul Kyzivat
Sent: Monday, April 22, 2013 6:24 PM
To: Barry Leiba
Cc: [email-masked]
Subject: Re: Document shepherd role

Perfect!

But I do think the writeup can usefully be started before WGLC.
It will then provide a place to keep useful information. For instance, if there is a lot of debate and controversy about some points, then info about that can be captured in the draft writeup while the memory of that is fresh. (Better than reading through months or years of email later to remember the details of that controversy.)

	Thanks,
	Paul

---

From: Barry Leiba <[email-masked]>
Date: Mon, 22 Apr 2013 19:11:29 -0400

> about that can be captured in the draft writeup while the memory of that
is
> fresh. (Better than reading through months or years of email later to

Yes, this is excellent input (and almost verbatim text) for the next
version of the draft.  Thanks.

Barry

---

From: "Adrian Farrel" <[email-masked]>
Date: Tue, 23 Apr 2013 00:17:37 +0100

In fact, and agreeing that this is useful input, why not start the shepherding
*process* much sooner? That is: issue tracking; milestone chasing; making sure
comments are addressed/resolved; etc.
 
While most chairs might already do this on their own or in conjunction with the
document authors, this is function that could be delegated within the working
group.
 
A
 
From: [email-masked] [mailto:[email-masked]] On Behalf Of
Barry Leiba
Sent: 23 April 2013 00:11
To: Paul Kyzivat
Cc: [email-masked]
Subject: Re: Document shepherd role
 
> about that can be captured in the draft writeup while the memory of that is
 
Yes, this is excellent input (and almost verbatim text) for the next version of
the draft.  Thanks.
 
Barry

---

From: Barry Leiba <[email-masked]>
Date: Mon, 22 Apr 2013 20:10:37 -0400

On Monday, April 22, 2013, Adrian Farrel wrote:

> In fact, and agreeing that this is useful input, why not start the
> shepherding *process* much sooner? That is: issue tracking; milestone
> chasing; making sure comments are addressed/resolved; etc.
>
>
...Which is, of course, what my draft is all about.

Barry

---

From: Benoit Claise <[email-masked]>
Date: Tue, 23 Apr 2013 12:49:46 +0200

On 23/04/2013 02:10, Barry Leiba wrote:
>     shepherding *process* much sooner? That is: issue tracking;
>     milestone chasing; making sure comments are addressed/resolved; etc.
>
+ 1

I believe it's time to revive draft-leiba-extended-doc-shepherd-01, 
modifying its content in the form of an experiment.

Regards, Benoit

---

From: Mark Townsley <[email-masked]>
Date: Tue, 23 Apr 2013 13:45:00 +0200

On Apr 23, 2013, at 12:00 AM, Barry Leiba wrote:

> Gee, Paul, you've provided the perfect intro.   Please check out my document, which I'm trying to figure out what to do with:

Excellent idea. 

Barry, sounds like something for the General AD to consider shepherding (or appointing a shepherd for!)

- Mark

---

From: Jari Arkko <[email-masked]>
Date: Tue, 23 Apr 2013 15:43:57 +0300

> Barry, sounds like something for the General AD to consider shepherding (or appointing a shepherd for!)

And I'm tracking it… and I like what the draft says, but I'm trying to figure out how to not repeat what happened last year when this draft went to the previous IESG and did not get approved. (I wasn't there, so I'm still trying to collect the pieces of history. But I think the issue had to do more with how it was packaged, rather than the actual content. A process experiment would seem like the right thing to do here.)

Jari

---

From: "Black, David" <[email-masked]>
Date: Tue, 23 Apr 2013 12:20:31 -0400

Hi Barry,

Hmm - it looks like I have some relevant "running code" experience with the WG
document stage of this from the IPS working group, which was a three-ring circus,
as the WG was effectively working on three major protocols concurrently.  Here's
the relevant charter text from: http://www.ietf.org/wg/concluded/ips.html:

  A technical coordinator will be identified and selected for each
  protocol encapsulation adopted as a work item by the group. This person
  will be responsible for coordinating the technical efforts of the group
  with respect to that encapsulation, working with and motivating the
  document editors, and evangelizing the group's work within both the
  community and relevant external organizations such as T10 and T11.

That structure was reasonably effective, due in part to the clear technical
division of scope of responsibility (by major protocol) among the technical
coordinators.  I'd use that structure again for a WG with similarly broad
scope and level of activity, and asking the coordinators to continue on to
serve as document shepherds makes sense to me.

Please note - during most of the IPS WG's lifetime there were two co-chairs,
and there were three for a while.  Although I was the last WG chair left
standing when IPS concluded, I did not run that entire effort single-handedly.

Thanks,
--David

From: [email-masked] [mailto:[email-masked]] On Behalf Of Barry Leiba
Sent: Monday, April 22, 2013 6:01 PM
To: Paul Kyzivat
Cc: [email-masked]
Subject: Re: Document shepherd role

Barry

        Thanks,
        Paul

Regards, Benoit

---

From: S Moonesamy <[email-masked]>
Date: Tue, 23 Apr 2013 17:46:54 -0700

Hi Benoit,
>WG document during the IESG call.

Thanks for responding to the AppsDir review of 
draft-ietf-ipfix-flow-selection-tech-14.  I hope that the author (who 
was responsive) did not go through the usual bad IETF experience.

I'll comment from an AppsDir perspective.  The only document 
shepherds who have interacted with AppsDir (I'll ignore Apps folks) are:

   Jeffrey Hutzelman
   Joel Halpern
   Warren Kumari
   Andrew Sullivan

The AppsDir reviewers do not usually take an antagonist position and 
go out of their way, in my opinion, to help the document 
authors.  Some of that work is document shepherd work instead of 
reviewer work.  The follow-up (to the review) ends up as more 
work.  Sometimes issues raised in an AppsDir review are not 
addressed.  I view that as a lack of consideration for the reviewer 
who has put in his/her free time to look at a draft in which he/she 
does not have any interest.  It's difficult enough to get reviews done.

Regards,
S. Moonesamy

---

From: Benoit Claise <[email-masked]>
Date: Wed, 24 Apr 2013 16:26:15 +0200

Hi,

Thanks for your feedback.
See in line.
> draft-ietf-ipfix-flow-selection-tech-14.
Not sure why you mentioned this draft specifically.
It's not the one I had in mind when I wrote the paragraph above.
Anyway, it doesn't matter. See below.
> I hope that the author (who was responsive) did not go through the 
> usual bad IETF experience.
>
> I'll comment from an AppsDir perspective.  The only document shepherds 
> who have interacted with AppsDir (I'll ignore Apps folks) are:
>
>   Jeffrey Hutzelman
>   Joel Halpern
>   Warren Kumari
>   Andrew Sullivan
>
> go out of their way, in my opinion, to help the document authors.  
> Some of that work is document shepherd work instead of reviewer work.  
> The follow-up (to the review) ends up as more work.
> Sometimes issues raised in an AppsDir review are not addressed.  I 
> view that as a lack of consideration for the reviewer who has put in 
> his/her free time to look at a draft in which he/she does not have any 
> interest.  It's difficult enough to get reviews done.
This should not happen!
One of the difficulties with directorates is that they have different 
goals, and therefore, send their draft review feedback to different 
people: to their respective ADs, to the directorate mailer, to the 
authors, to the WG. Some are not even archived.
Recently, we realized that some reviews were not reaching the right 
persons. At least not the draft AD ... who should be one of persons 
follow up.
In the OPS directorate, we have solved this by inserting this note in 
the review request email:

    Reviews are sent the OPS DIR mailing list ([email-masked]) and to
    the authors, WG chairs, and respective AD. The way to reach the
    authors, WG chairs, and respective AD is to send an email to
    <draft-name>[email-masked]

To make the link with the document shepherd, one issue needs to be 
fixed: currently the <draft-name>[email-masked] doesn't contain the 
doc shepherd. I'll work on that one.

Regards, Benoit

---

From: joel jaeggli <[email-masked]>
Date: Wed, 24 Apr 2013 10:42:03 -0700

On 4/22/13 3:04 PM, Paul Kyzivat wrote:
>> In busy working groups, ones with a lot of documents, it isn't 
>> unusual for the chairs to divide up responsibility for the active WG 
>> drafts.  When those drafts go into the IESG, the WG chair who has 
>> been responsible for the document during the WG process usually 
>> shepherds the draft through the IESG.  That works pretty well, in my 
>> experience.
>>
>> In less busy groups, ones with fewer drafts, the chairs may work 
>> together on all of the documents.  They then have to assign a 
>> shepherd at the end.  Depending on the roles of the individual 
>> chairs, this can work well, but sometimes the chair needs to fill in 
>> a lot of knowledge to do the shepherding task.  In these cases, I 
>> agree it might make sense to explicitly decide who will shepherd the 
>> draft earlier in the process.
>
> In the groups I chair we haven't overtly considered who will shepherd 
> a document until after WGLC. Maybe this isn't a problem for other 
> groups. But for mine I'm just discovering that starting this earlier 
> would be helpful.

So I don't think the task is especially onerous, hard or requires deeply 
advance planning. The part that chairs are generally good at and  
generally do well in the case where they are the shepherds  is reviewing 
the consensus,  and ticking the ipr boxes.

---

From: Behcet Sarikaya <[email-masked]>
Date: Thu, 25 Apr 2013 13:37:42 -0500

+1

Regards,

Behcet

On Wed, Apr 24, 2013 at 12:42 PM, joel jaeggli <[email-masked]> wrote:

> advance planning. The part that chairs are generally good at and  generally
> do well in the case where they are the shepherds  is reviewing the
> consensus,  and ticking the ipr boxes.
>
>