Document Shepherding from Working Group Last Call to Publication
draft-ietf-proto-wgchair-doc-shepherding-09

State Change Notice email list have been change to henrik@levkowetz.com, margaret@thingmagic.com, mankin@psg.com,dmm@1-4-5.net,lars.eggert@nokia.com from henrik@levkowetz.com, margaret@thingmagic.com, mankin@psg.com,dmm@1-4-5.net

[Ballot comment]
I wonder how we can have DISCUSSes on this document while at the same
we must believe that this document is 'good enough' as we are all
using it for most of our working groups!

[Ballot discuss]
The examples in Appendix A do not follow the outline proposed in
  Section 3.1 paragraph (1.k).

  At the WG Chairs lunchtime session during IETF 67, the suggestion was
  made to add a section to the Document Shepherd Write-Up that addresses
  the security-relevant BCPs.  For RFC 4107 the questions might say:

    Does this protocol make use of cryptographic keys?  If so, is manual
    key management used instead of automated key management?  If manual
    key management is used, what provision in section 2.2 of RFC 4107
    makes this an appropriate choice?

  I suspect that other BCPs will be written in the future that will lead
  to similar sections, not just for security topics, but for BCPs from
  just about any IETF Area.  As a result, it seems like it would be
  better to post the Document Shepherd Write-Up Template, and put a
  pointer to it in this document.  This document could include the
  current template with an appropriate introduction, like:

    The initial Document Shepherd Write-Up Template is included here,
    but changes are expected over time.

[Ballot comment]
I'd be really grumpy if one of my document sheppherds filed an appeal
over an outstanding discuss that another AD is holding.  It really
seems that by the time you are considering appeals and override votes,
perhaps things have risen to the level where the responsible AD should
be handling the negotiations.

[Ballot discuss]
If we're going to rename the proto shepherd to document shepherd we
must rename sheppherding AD to responsible AD in the tracker or we
will never avoid huge confusion.


This document attempts to redefine the ballot, adding a personnel
section and renaming protocol quality to document quality.  The IESG
should confirm it's happy with that.

[Ballot discuss]
1. Why isn't this document going for BCP? It is clearly a process document. Although on a small part of the IETF process. In addition it is something all our WG chairs or other potential shepherds will need to live with. Thus having made it into a BCP seems to better capture the content and its applicability.

[Ballot discuss]
1. Why isn't this document going for BCP? It is clearly a process document. Although on a small part of the IETF process. In addition it is something all our WG chairs or other potential shepherds will need to live with. Thus having made it into a BCP seems to better capture the content and its applicability.

2. I would also like to know why IETF last call (when applicable) is not included in the shepherding tasks. To me it seems strange to not have the shepherd responsible for resolving last call comments. To me it seems that there would be need for an additional section 3 chapter in between 3.2 and 3.3.

[Ballot comment]
1. Section 3

During IESG evaluation, following up on all IESG feedback ("DISCUSS" and "COMMENT" items) related to the shepherded document, as described in Section 3.3.

Any reason not to include "ABSTAIN" contents as feedback?

2. Is there any reference for who is the Responsible Area Director? Is this the same as WG Area Advisor?

3. In 2e I am slightly confused by the use of the construct 'strongly RECOMMENDED'. I believe that we should not allow usage of intermediate constructs between 2119 keywords and would recommend to pick one of RECOMMENDED (with no strength marking) or MUST.

4. Section 6 - 'If the document shepherding process is not used, the Responsible Area Director acts as Document Shepherd, just as he or she did in the past.' - better say '... just as per the existing procedures of shepherding by Area Directors.' (he or she may not have been an AD in the past)

[Ballot comment]
I don't quite like the text of
          This requires
          the Responsible Area Director to present to the Document
          Shepherd any Last Call Issues raised only to the IESG.
but not sure how to improve.

I don't want this to be interpreted as the exact email or even the person that raised the complaint must be sent to the shepherd. I do agree the shepherd needs to know about issues that require changes to the document.

[Ballot comment]
Nit:

This parenthetical expression is not closed:

(because it was created by the "PROcess
  and TOols" or PROTO [PROTO] team,

The document consistently says that the document
shepherd should be a single person (see section 3.
especially).  I have personally run PROTO with both
working group chairs taking joint responsibility.  I
think it works.  Softening the language on that to
allow WG chairs to work in double harness would
be valuable, in my opinion.

Section 3.1 adds this section to the common write-up:

Personnel
            Who is the Document Shepherd for this document?  Who is the
            Responsible Area Director?

above that, the document says:

A final sentence of the Document Announcement Write-Up, simply placed
  as a line at the end of the "Document Quality" section, can state the
  names of the Document Shepherd and the Responsible Area Director,
  because the announcement will not otherwise acknowledge them.  The
  Document Shepherd SHOULD add this information and the Responsible
  Area Director SHOULD add it if it is not already there.

That seems to indicate that the same information goes in the Document quality
section, rather than in its own heading.  Resolving that seems to me useful.

On IANA actions, the document says:

  In summary, the task of shepherding the IANA actions is overlooked
  but is as important to coordinate and manage as all the other
  document reviews the Document Shepherd has managed.  As with those,
  the Document Shepherd contributes greatly to quality and timeliness
  of the document by effective and responsive shepherding of the IANA
  requests.

Does this mean to say "is often overlooked"?

In Section 6, the document says:

1.  Cases, where the Document Shepherd is the primary author or
      editor of a large percentage of the documents produced by the
      working group.
2.  Cases, where the Responsible Area Director expects communication
      difficulties with the Document Shepherd (either due to
      experience, strong views stated by the Document Shepherd, or
      other issues).

  3.  Cases, where the working group itself is either very old, losing
      energy, or winding down, i.e., cases, where it would not be
      productive to initiate new processes or procedures.

The syntax of these is hard to parse. I think the last of them applies
only to working groups that pre-date PROTO (it would not introduce
a new procedure to tired WGs that post-date PROTO).  As something
that is either already dated or soon will be, should it be struck?

Frankly, I would recommend cutting that whole section, and replacing
it with "When the responsible area director or proposed PROTO shepherd
feel that the process is not appropriate, the responsible area director
may server as document shepherd, as she or he does for non-WG
documents."