Subject: [proto-team] Submission of update to document in IESG Eval

From: Allison Mankin <[email-masked]>
Date: Mon, 23 Oct 2006 06:54:13 +0000

Please accept draft-ietf-proto-wgchair-doc-shepherding--08.txt, an update
responding to various AD coments and several comments from student
and others

--------------------------------

PROTO Team                                                  H. Levkowetz
Internet-Draft                                                  Ericsson
Intended status: Informational                                  D. Meyer
Expires: April 25, 2007                       Cisco/University of Oregon
                                                               L. Eggert
                                                                     NEC
                                                               A. Mankin
                                                        October 22, 2006

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

Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on April 25, 2007.

Copyright Notice

   Copyright (C) The Internet Society (2006).

Abstract

   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

Levkowetz, et al.        Expires April 25, 2007                 [Page 1]

Internet-Draft            Document Shepherding              October 2006

   submitted to the IESG for publication.  Before this, the Area
   Director responsible for the working group has traditionally filled
   the shepherding role.

   A Document Shepherd's responsibilities include:

   o  Providing the Document Shepherd Write-Up accompanying a document
      that is forwarded to the IESG when publication is requested.

   o  During AD Evaluation by the Responsible Area Director, managing
      the discussion between the editors, the working group, and the
      Responsible Area Director.

   o  During IESG evaluation, following up on all IESG feedback
      ("DISCUSS" and "COMMENT" items) related to the shepherded
      document.

   o  Following up on IANA and RFC Editor requests in the post-approval
      shepherding of the document.

   In summary, a Document Shepherd continues to care for a shepherded
   document during its post-WG lifetime just as he or she has cared for
   it while responsible for the document in the working group.

Levkowetz, et al.        Expires April 25, 2007                 [Page 2]

Internet-Draft            Document Shepherding              October 2006

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
   2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  5
   3.  Process Description  . . . . . . . . . . . . . . . . . . . . .  5
     3.1.  Document Shepherd Write-Up . . . . . . . . . . . . . . . .  6
     3.2.  Document Shepherding during AD Evaluation  . . . . . . . . 10
     3.3.  Document Shepherding during IESG Evaluation  . . . . . . . 11
   4.  Shepherding the Document's IANA Actions  . . . . . . . . . . . 14
   5.  Document Shepherding after IESG Approval . . . . . . . . . . . 15
   6.  When Not to Use the Document Shepherding Process . . . . . . . 16
   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 16
   8.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 16
   9.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 17
   10. Informative References . . . . . . . . . . . . . . . . . . . . 17
   Appendix A.  Example Document Announcement Write-Ups . . . . . . . 18
     A.1.  Example Document Announcement Write-Up for
           draft-ietf-avt-rtp-midi-format . . . . . . . . . . . . . . 18
     A.2.  Example Document Announcement Write-Up for
           draft-ietf-imss-ip-over-fibre-channel  . . . . . . . . . . 19
   Appendix B.  Working Documents . . . . . . . . . . . . . . . . . . 20
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20
   Intellectual Property and Copyright Statements . . . . . . . . . . 22

Levkowetz, et al.        Expires April 25, 2007                 [Page 3]

Internet-Draft            Document Shepherding              October 2006

1.  Introduction

   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 the part of a document's life cycle that
   occurs after the working group and document editor have forwarded it
   to the IESG for publication.

   By the end of 2004, the IESG had evaluated the utility of the PROTO
   methodologies based on data obtained through several pilot projects
   that had run throughout the year, and subsequently decided to adopt
   the PROTO process for all documents and working groups.  This
   document describes this process.

   The methodologies developed and piloted by the PROTO team focus on
   the working group chair or secretary as the primary Document
   Shepherd.  The primary objective of this document shepherding process
   is to improve document-processing throughput and document quality by
   enabling a partnership between the Responsible Area Director and the
   Document Shepherd.  In particular, this partnership has the explicit
   goal of enfranchising the Document Shepherd while at the same time
   offloading a specific part of the follow-up work that has
   traditionally been responsibility of the Responsible Area Director.
   The Responsible Area Director has tens or many tens of documents to
   follow, while the Document Shepherd has only a few at a time.
   Flowing the responsibility to the working group level can ensure more
   attention and more timely response.

   Consequently, the document shepherding process includes follow-up
   work during all document-processing stages after Working Group Last
   Call, i.e., during AD Evaluation of a document, during IESG
   evaluation, and during post-approval processing by IANA and the RFC
   Editor.  In these stages, it is the responsibility of the Document
   Shepherd to track and follow up on feedback received on a document
   from all relevant parties.

   The Document Shepherd is usually a chair of the working group that
   has produced the document.  In consultation with the Responsible Area
   Director, the chairs may instead decide to appoint the working group
   secretary as the responsible Document Shepherd.

   The remainder of this document is organised as follows: Section 3

Levkowetz, et al.        Expires April 25, 2007                 [Page 4]

Internet-Draft            Document Shepherding              October 2006

   outlines the overall document shepherding process.  Section 3.1
   describes the Document Shepherd Write-Up that accompanies the
   publication request of a document.  Section 3.2 describes the AD
   Evaluation shepherding process and Section 3.3 describes IESG DISCUSS
   shepherding.  Finally, Section 6 describes those cases in which the
   document shepherding process should not be used.

2.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in BCP 14, RFC 2119
   [RFC2119].

3.  Process Description

   The document shepherding process consists of the following tasks:

   o  Providing the Document Shepherd Write-Up accompanying a document
      that is forwarded to the IESG when publication is requested, as
      described in Section 3.1.

   o  During AD Evaluation of the document by the Responsible Area
      Director, managing the discussion between the editors, the working
      group and the Responsible Area Director, as described in
      Section 3.2.

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

   o  Following up on IANA and RFC Editor requests as described in
      Section 4 and Section 5.

   The shepherd must keep the document moving forward, communicating
   about it with parties who review and comment it.  The shepherd must
   obtain the working group's consensus for any substantive proposed
   changes.  The shepherd is the leader for the document and for the
   working group, and maintains a critical and technical perspective.
   In summary, the Document Shepherd continues to care for a shepherded
   document during its post-WG lifetime just as he or she has done while
   responsible for the document in the working group.

   Before any document shepherding takes place, a single Document
   Shepherd MUST be identified for a document (he or she will be named
   in the Document Shepherd Write-Up) .  Frequently, the chairs and the

Levkowetz, et al.        Expires April 25, 2007                 [Page 5]

Internet-Draft            Document Shepherding              October 2006

   Responsible Area Director will decide that the working group will
   adopt the PROTO process for all their future documents.  After that
   decision, the chairs, in consultation with the Responsible Area
   Director, decide on who should act as Document Shepherd for any given
   document.  This is typically and by default one of the chairs of the
   working group.  In consultation with the Responsible Area Director,
   the chairs MAY also decide to appoint the working group secretary as
   Document Shepherd for a given document.  The Document Shepherd SHOULD
   NOT be an editor of the shepherded document.

   It is intended that the Document Shepherd role is filled by one
   person during the entire shepherding process.  However, situations
   may occur when the Document Shepherd role may be reassigned to
   different persons during the lifetime of a document.  It is up to the
   chairs and Responsible Area Director to identify situations when this
   may become necessary, and then consult to appoint a new Document
   Shepherd.

   It is important to note that the document shepherding process only
   applies to documents that are the product of a working group.  It
   does not apply to documents that originate elsewhere.  Additionally,
   Section 6 discusses other instances in which the document shepherding
   process does not apply.

3.1.  Document Shepherd Write-Up

   When a working group decides that a document is ready for submission
   to the IESG for publication, it is the task of the Document Shepherd
   to complete a "Document Shepherd Write-Up" for the document.

   There are two parts to this task.  First, the Document Shepherd
   answers questions (1.a) to (1.i) below to give the Responsible Area
   Director insight into the working group process that applied to this
   document.  Note that while these questions may appear redundant in
   some cases, they are written to elicit information that the
   Responsible Area Director must be aware of (to this end, pointers to
   relevant entries in the WG archive are helpful).  The goal here is to
   inform the Responsible Area Director about any issues that may have
   come up in IETF meetings, on the mailing list, or in private
   communication that they should be aware of prior to IESG evaluation
   of the shepherded document.  Any significant issues mentioned in the
   questionnaire will probably lead to a follow-up discussion with the
   Responsible Area Director.

   The second part of the task is to prepare the "Document Announcement
   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 the Document Announcement Write-Up.

Levkowetz, et al.        Expires April 25, 2007                 [Page 6]

Internet-Draft            Document Shepherding              October 2006

   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.

   Some examples of Document Announcement Write-Ups are included in
   Appendix A, and there are many more examples with subject lines such
   as "Protocol Action" and "Document Action" in the IETF-announce
   mailing list archive.

   (1.a)  Who is the Document Shepherd for this document?  Has the
          Document Shepherd personally reviewed this version of the
          document and, in particular, does he or she believe this
          version is ready for forwarding to the IESG for publication?

   (1.b)  Has the document had adequate review both from key WG members
          and from key non-WG members?  Does the Document Shepherd have
          any concerns about the depth or breadth of the reviews that
          have been performed?

   (1.c)  Does the Document Shepherd have concerns that the document
          needs more review from a particular or broader perspective,
          e.g., security, operational complexity, someone familiar with
          AAA, internationalization or XML?

   (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 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 the WG has discussed those issues and has indicated
          that it still wishes to advance the document, detail those
          concerns here.

   (1.e)  How solid is the WG consensus behind this document?  Does it
          represent the strong concurrence of a few individuals, with
          others being silent, or does the WG as a whole understand and
          agree with it?

   (1.f)  Has anyone threatened an appeal or otherwise indicated extreme
          discontent?  If so, please summarise the areas of conflict in
          separate email messages to the Responsible Area Director.  (It
          should be in a separate email because this questionnaire is
          entered into the ID Tracker.)

Levkowetz, et al.        Expires April 25, 2007                 [Page 7]

Internet-Draft            Document Shepherding              October 2006

   (1.g)  Has the Document Shepherd personally verified that the
          document satisfies all ID nits?  (See
          http://www.ietf.org/ID-Checklist.html and
          http://tools.ietf.org/tools/idnits/).  Boilerplate checks are
          not enough; this check needs to be thorough.  Has the document
          met all formal review criteria it needs to, such as the MIB
          Doctor, media type and URI type reviews?

   (1.h)  Has the document split its references into normative and
          informative?  Are there normative references to documents that
          are not ready for advancement or are otherwise in an unclear
          state?  If such normative references exist, what is the
          strategy for their completion?  Are there normative references
          that are downward references, as described in [RFC3967]?  If
          so, list these downward references to support the Area
          Director in the Last Call procedure for them [RFC3967].

   (1.i)  Has the Document Shepherd verified that the document IANA
          consideration section exists and is consistent with the body
          of the document?  If the document specifies protocol
          extensions, are reservations requested in appropriate IANA
          registries?  Are the IANA registries clearly identified?  If
          the document creates a new registry, does it define the
          proposed initial contents of the registry and an allocation
          procedure for future registrations?  Does it suggested a
          reasonable name for the new registry?  See
          [I-D.narten-iana-considerations-rfc2434bis].  If the document
          describes an Expert Review process has Shepherd conferred with
          the Responsible Area Director so that the IESG can appoint the
          needed Expert during the IESG Evaluation?

   (1.j)  Has the Document Shepherd verified that sections of the
          document that are written in a formal language, such as XML
          code, BNF rules, MIB definitions, etc., validate correctly in
          an automated checker?

   (1.k)  The IESG approval announcement includes a Document
          Announcement Write-Up.  Please provide such a Document
          Announcement Writeup?  Recent examples can be found in the
          "Action" announcements for approved documents.  The approval
          announcement contains the following sections:

          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.

Levkowetz, et al.        Expires April 25, 2007                 [Page 8]

Internet-Draft            Document Shepherding              October 2006

          Working Group Summary
             Was there anything in WG process that is worth noting?  For
             example, was there controversy about particular points or
             were there decisions where the consensus was particularly
             rough?

          Document Quality
             Are there existing implementations of the protocol?  Have a
             significant number of vendors indicated their plan to
             implement the specification?  Are there any reviewers that
             merit special mention as having done a thorough review,
             e.g., one that resulted in important changes or a
             conclusion that the document had no substantive issues?  If
             there was a MIB Doctor, Media Type or other expert review,
             what was its course (briefly)?  In the case of a Media Type
             review, on what date was the request posted?

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

   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 entire Document Shepherd Write-up to the working group
   mailing list.  If the Document Shepherd feels that information which
   may prove to be sensitive, lead to possible appeals or is personal
   information needs to be written up, it SHOULD be sent in direct email
   to the Responsible Area Director, because the Document Shepherd
   Write-Up is published openly in the tracker.  Question 1(f) of the
   Write-Up covers any material of this nature and specifies this more
   confidential handling.

   The Document Shepherd Write-Up is entered into the ID Tracker
   [IDTRACKER] as a "Comment."  The name and email address of the
   Document Shepherd are entered into the ID Tracker, currently as a
   "Brief Note" (this may change in the future).  The email address of
   the Document Shepherd MUST also be added to the "State or Version
   Change Notice To" field (typically the email addresses of all working
   group chairs, authors and the Secretary will be added).

   Entering the name and email of the Document Shepherd into the ID
   Tracker is REQUIRED to ensure that he or she will be copied on the
   email exchange between the editors, chairs, the IESG, the IESG
   secretariat, IANA and the RFC Editor during the review and approval
   process.  There are still manual steps required for these parties to
   ensure they include the Document Shepherd, but it is hoped that in
   future, automated tools will ensure that Document Shepherds (and

Levkowetz, et al.        Expires April 25, 2007                 [Page 9]

Internet-Draft            Document Shepherding              October 2006

   others) receive necessary communications.

   The contact information for the Document Shepherd is also important
   for the Gen-ART [GEN-ART] Directorate and other directorates, so they
   can know to whom to address reviews, in addition to the Responsible
   Area Director.

3.2.  Document Shepherding during AD Evaluation

   The steps for document shepherding during AD Evaluation are as
   follows:

   (2.a)  The Responsible Area Director reads, evaluates and comments on
          the document, as is the case when not using the document
          shepherding process.  If the Responsible Area Director
          determines that the document is ready for IESG Evaluation, he
          or she indicates this to the Document Shepherd and the
          document shepherding process continues as described in
          Section 3.3.

   (2.b)  If the Responsible Area Director has identified issues with a
          document that must be addressed before IESG Evaluation can
          commence, he or she sends a full evaluation to the Document
          Shepherd and SHOULD also enter the review into the ID Tracker.

   (2.c)  The Document Shepherd reads the AD Evaluation comments, making
          very certain that all comments are understood, so that it is
          possible to follow up on them with the editors and working
          group.  If there is some uncertainty as to what is requested,
          this SHOULD be resolved with the Responsible Area Director.

   (2.d)  The Document Shepherd sends the AD Evaluation comments to the
          editors and to the working group mailing list, in order to
          have a permanent record of the comments.  It is RECOMMENDED
          that the Document Shepherd solicit from the editors an
          estimate on when the required changes will be complete and a
          revised document can be expected.  Working groups that use
          issue tracking SHOULD also record the issues (and eventually
          their resolution) in their issue tracker.

   (2.e)  During the production of a revised document that addresses the
          AD Evaluation comments, it is strongly RECOMMENDED that the
          editors keep a list showing how each comment was addressed and
          what the revised text is.  It is strongly RECOMMENDED that
          this list be forwarded to the Responsible Area Director
          together with the revised document.

Levkowetz, et al.        Expires April 25, 2007                [Page 10]

Internet-Draft            Document Shepherding              October 2006

   (2.f)  In the event that the editors or working group disagrees with
          a comment raised by the Responsible Area Director or has
          previously considered and dismissed the issue, the Document
          Shepherd MUST resolve the issue with the Responsible Area
          Director before a revised document can be submitted.

   (2.g)  The Document Shepherd iterates with the editors (and working
          group, if required) until all outstanding issues have been
          resolved and a revised document is available.  At this point,
          the Document Shepherd notifies the Responsible Area Director
          and provides him or her with the revised document, the summary
          of issues and the resulting text changes.

   (2.h)  The Responsible Area Director verifies that the issues he or
          she found during AD Evaluation are resolved in the revised
          version of the document by starting the process described in
          this section at step (2.a).

3.3.  Document Shepherding during IESG Evaluation

   During IESG Evaluation of a document, ADs can bring forward two kinds
   of remarks about a document: DISCUSS item and COMMENT items.  A
   DISCUSS blocks a document's approval process until it has been
   resolved; a COMMENT does not.  This section details the steps that a
   Document Shepherd takes to resolve any DISCUSS and COMMENT items
   brought forward against a shepherded document during IESG Evaluation.

   Note that DISCUSS and COMMENT items are occasionally written in a
   manner that makes their intent unclear.  In these cases, the Document
   Shepherd SHOULD start a discussion with the ADs who brought the items
   up to clarify their intent, keeping the Responsible Area Director
   informed.  If this fails to clarify the intent, the Responsible Area
   Director may need to work towards a clarification inside the IESG.

   (3.a)  Leading up to the IESG conference call, the Document Shepherd
          may see emails about the document from directorate reviewers
          on behalf of one or more ADs and also emailed copies of
          DISCUSS and COMMENT items entered into the ID Tracker.  The
          Document Shepherd SHOULD immediately begin to work on
          resolving DISCUSS and COMMENT items with the ADs who have
          raised them, keeping the Responsible Area Director copied on
          the email exchange, so that he or she is able to support the
          the activity during the conference call.  When dealing with
          directorate reviews, the Document Shepherd MUST involve the
          ADs to whom these directorates report to ensure that these ADs
          consider the review comments that need resolving.

Levkowetz, et al.        Expires April 25, 2007                [Page 11]

Internet-Draft            Document Shepherding              October 2006

   (3.b)  Immediately following the conference call, when the document
          changes state from the "IESG Evaluation" state to one of the
          states requiring Document Shepherd action, e.g., "IESG
          Evaluation: Revised ID Needed" or "IESG Evaluation: AD
          Followup", the Document Shepherd will receive email.  A state
          of "AD Followup" typically signifies the Responsible Area
          Director's hope that a resolution may be possible through a
          continued discussion or (more usually) through a small set of
          changes as "Notes to the RFC Editor."

          Note that there may be very exceptional cases when DISCUSS
          items are registered after an IESG conference call.  In these
          cases, the AD who has raised the DISCUSS MUST notify the
          Document Shepherd about it.  (The notification facility in the
          ID Tracker is very convenient for this purpose and also for
          the cases where the DISCUSS and COMMENT items are updated
          after they are partially resolved.)

   (3.c)  The Document Shepherd then queries the ID Tracker to collect
          the remaining DISCUSS and COMMENT items raised against the
          document.  The Document Shepherd analyses these items and
          initialises contact with the ADs who have placed them.  The
          Responsible Area Director MUST be copied on all correspondence
          related to active DISCUSS or COMMENT items.  This does not
          place the Responsible Area Director in the critical path
          towards a resolution, but should keep him or her informed
          about the state of the discussion.

         +-------+              +-------+               +-------+
         | (3.b) | -----------> | (3.c) | ------------> | (3.d) |
         +-------+  Comments    +-------+   Comments    +-------+
                    collected    /|\  |    understood
                                  |   |
                                  |   | Comments not fully understood
                                  |   | (Further AD/Document Shepherd
                                  |   |  discussion required)
                                  +---+

   (3.d)  The Document Shepherd then coordinates the resolution of
          DISCUSS and COMMENT items and builds a consistent
          interpretation of the comments.  This step is similar to much
          of the process described in Section 3.2.

Levkowetz, et al.        Expires April 25, 2007                [Page 12]

Internet-Draft            Document Shepherding              October 2006

         +-------+                  +-------+
         | (3.c) | ---------------> | (3.d) |
         +-------+    Consistent    +-------+
            /|\     interpretation      |
             |                          | Further AD/Document Shepherd
             |                          | discussion required
             +--------------------------+

   (3.e)  The Document Shepherd then communicates the DISCUSS and
          COMMENT items to the document editors and the working group,
          alerting them of any changes to the document that have
          accumulated during IESG processing, such as "Notes to the RFC
          Editor."  If any changes will be substantive, the Document
          Shepherd, in consultation with the Responsible Area Director,
          as during other stages, MUST seek working group consensus.

   (3.f)  After the editors resolve the DISCUSS and COMMENT items, the
          Document Shepherd reviews the resulting new version of the
          document, which will be a revised document, a set of "Notes to
          the RFC Editor", or both, using his or her technical expertise
          to ensure that all raised DISCUSS and COMMENT issues have been
          resolved.

          Note that the Document Shepherd MAY also suggest resolutions
          to DISCUSS and COMMENT items, enter them into an issue
          tracker, or perform other steps to streamline the resolution
          of the evaluation comments.  It is very important to resolve
          the comments in a timely way, while the discussion is current
          for everyone involved.

   (3.g)  When the Document Shepherd is satisfied that the revised
          document addresses the evaluation comments, he or she
          communicates the resolution to the Responsible Area Director
          and the ADs that had raised the DISCUSS and COMMENT items.

   (3.h)  Each AD who had raised a DISCUSS checks whether the
          communicated resolution addresses his or her items.  If it
          does, the AD will clear the DISCUSS.  It it does not, the AD
          notifies the Document Shepherd and adds information to the ID
          Tracker explaining why the DISCUSS was not resolved.  The
          Document Shepherd informs the working group accordingly.
          (COMMENT items need not be checked and cleared, because they
          do not block the document, but ADs are encouraged to do so.)

          If a DISCUSS was not resolved to the satisfaction of the AD
          that has raised it or the Responsible Area Director, two
          possibilities exist:

Levkowetz, et al.        Expires April 25, 2007                [Page 13]

Internet-Draft            Document Shepherding              October 2006

          (a)  The process returns to step (3.d), or

          (b)  If no progress can be made on the resolution of the
               DISCUSS with the AD who has raised it, despite
               clarification and additional involvement of the
               Responsible Area Director, the Document Shepherd and
               working group might as a very last resort consider an
               appeal in accordance with the procedures described in
               [RFC2026] and referred to in [RFC2418].  The Document
               Shepherd SHOULD review the IESG's Discuss Criteria
               guidelines [I-D.iesg-discuss-criteria] and discuss with
               the Responsible Area Director whether there might be
               consideration against the unresolved DISCUSS by the rest
               of the IESG due to these guidelines.

          Once the process above has cleared all DISCUSS items, document
          shepherding continues with step (3.i).

   (3.i)  The Responsible Area Director moves the document to the
          "Approved - Announcement to be sent" state in the ID Tracker.
          If he or she deems the changes to the revised document
          significant, there may be a new WG last call, or possibly a
          new IETF last call.  The document goes through a new full IESG
          Evaluation process if there is a new IETF last call.

4.  Shepherding the Document's IANA Actions

   IETF working group documents often include considerations requiring
   actions by the IANA, such as creating a new registry or adding
   information to an existing registry, perhaps after consulting an
   IESG-appointed Expert.  Sometimes the actions required are by the
   IESG, such as appointment of a new Expert.  IANA-related processing
   may also include a specified type of Expert review, such as review of
   proposed MIME media types on the designated ietf-types mailing list.
   The IANA reviews IETF documents and requests responses at any or all
   of the following times: in response to IETF Last Call, during the
   IESG Evaluation review of the document, and at the time when the IANA
   performs actions in its web-based registry for the document, usually
   but not always after IESG approval of the document.  More details of
   the IANA process and IETF interaction are found in
   [I-D.narten-iana-considerations-rfc2434bis].

   Whenever an IANA request comes, in whatever period, the requester
   from IANA MUST ensure that the Document Shepherd and the Responsible
   Area Director both receive the request.  The Document Shepherd is
   responsible for responding as rapidly as possible.  He or she should
   discuss requests that introduce any possible concerns with the

Levkowetz, et al.        Expires April 25, 2007                [Page 14]

Internet-Draft            Document Shepherding              October 2006

   Working Group.  The Document Shepherd and the Responsible Area
   Director may decide in consultation that an IANA request leads to a
   change that needs additional review or approval.

   In general, the Working Group Shepherd ensures that the IANA process
   completes, checks that the registry is correct and that the IANA
   Matrix (www.iana.org/numbers.html) is complete and consistent, and
   troubleshoots when all is not well.  At the end of IANA processing,
   the Document Shepherd should be sure that the RFC Editor has
   acknowledged IANA conclusion, that the handoff has been made.

   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.

5.  Document Shepherding after IESG Approval

   After the IESG Evaluation and resolution described in Section 3.3,
   the IESG approves the document, and the Responsible Area Director
   uses the tracker to ask for any final changes to the Document
   Announcement Write-Up and to ask for it to be issued.  The Document
   Shepherd may have some edits for the Responsible Area Director, such
   as minor Notes to the RFC Editor, and this is the time to consult and
   provide them.

   The announcement goes to the general community and to the RFC Editor,
   and now the Document Shepherd (identified in the Announcemen
   Write-Up) continues to shepherd the document through its technical
   publication.  The RFC Editor currently makes a number of types of
   requests to the authors, Document Shepherd and Responsible Area
   Director.  The Document Shepherd SHOULD lead in responding to the RFC
   editor and shepherding the document through its technical
   publication, through the post-approval period.  The RFC Editor
   request types include: editorial queries about dangling, missing,
   informative and normative citations (good shepherding should try to
   pre-catch these, but they happen); requests for unedited source, e.g.
   xml; occasional technical comments; and copy-edits for review and
   close scrutiny by the authors (AUTH48).  On the latter, the Document
   Shepherd SHOULD lead in checking that copy-edits have in no case
   affected a consensus wording of the working group which prepared the
   document, and in bringing speed to this checking by multiple co-
   authors.  The Document Shepherd also consults with the Responsible
   Area Director in reviewing proposed post-approval changes to the
   document by any authors.  These may require Area Director approval,

Levkowetz, et al.        Expires April 25, 2007                [Page 15]

Internet-Draft            Document Shepherding              October 2006

   and they often need to be presented to the working group for consent
   if not a full consensus procedure.  As in other periods of document
   review, the Document Shepherd provides attentiveness and timeliness
   by serving as the informed representative of the document and helping
   its advancement and its integrity.

6.  When Not to Use the Document Shepherding Process

   As mentioned in Section 3, the Document Shepherd SHOULD NOT be an
   editor of the shepherded document.  If this cannot be avoided by
   making another working group chair or secretary the Document
   Shepherd, the document shepherding process SHOULD NOT be used.  There
   are several other cases in which the document shepherding process
   SHOULD NOT be used.  These include:

   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.

   Finally, note that other cases exist in which using the document
   shepherding process may not be productive.  The final determination
   as to whether to use the document shepherding process or not is left
   to the Responsible Area Director.  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.

7.  Security Considerations

   This document specifies a change to IETF document-processing
   procedures.  As such, it neither raises nor considers protocol-
   specific security issues.

8.  IANA Considerations

   This document creates no new requirements on IANA namespaces or other
   IANA requirements.

Levkowetz, et al.        Expires April 25, 2007                [Page 16]

Internet-Draft            Document Shepherding              October 2006

9.  Acknowledgments

   This document is the product of PROTO team, which includes the
   authors as well as Bill Fenner, Barbara Fuller, and Margaret
   Wasserman.  Aaron Falk worked actively in PROTO till the start of
   2006 and worked on earlier versions of the document.

   The Document Shepherd Write-Up originated in an idea by John Klensin.
   Thomas Narten and Margaret Wasserman implemented it for the entire
   Internet Area, and their template was the basis of the version used
   today.

   Colin Perkins wrote the Document Announcement Write-Up for
   draft-ietf-avt-rtp-midi-format included in Appendix A.1.  David Black
   wrote the Document Announcement Write-Up for
   draft-ietf-imss-ip-over-fibre-channel included in Appendix A.2.

   Frank Ellermann and Olafur Gudmundsson have suggested improvements to
   the document during IETF Last Call.

10.  Informative References

   [RFC2026]  Bradner, S., "The Internet Standards Process -- Revision
              3", BCP 9, RFC 2026, October 1996.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2418]  Bradner, S., "IETF Working Group Guidelines and
              Procedures", BCP 25, RFC 2418, September 1998.

   [RFC3967]  Bush, R. and T. Narten, "Clarifying when Standards Track
              Documents may Refer Normatively to Documents at a Lower
              Level", BCP 97, RFC 3967, December 2004.

   [I-D.iesg-discuss-criteria]
              Peterson, J., "DISCUSS Criteria in IESG Review",
              draft-iesg-discuss-criteria-02 (work in progress),
              February 2006.

   [I-D.narten-iana-considerations-rfc2434bis]
              Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs",
              draft-narten-iana-considerations-rfc2434bis-05 (work in
              progress), September 2006.

   [IDTRACKER]

Levkowetz, et al.        Expires April 25, 2007                [Page 17]

Internet-Draft            Document Shepherding              October 2006

              "The IETF Internet-Draft Tracker", Web
              Application: https://datatracker.ietf.org/, 2002.

   [PROTO]    "The IESG PROcess and TOols (PROTO) Team", Web
              Page: http://psg.com/~mrw/PROTO-Team, 2004.

   [GEN-ART]  "The General Area Review Team (GEN-ART)", Web Page:
               http://www.alvestrand.no/ietf/gen/review-guidelines.html,
              2005.

Appendix A.  Example Document Announcement Write-Ups

   This appendix includes two examples of Document Announcement Write-
   Ups.  Many more examples with Subject lines such as "Protocol Action"
   and "Document Action" can be found in the IETF-announce mailing list
   archive.

A.1.  Example Document Announcement Write-Up for
      draft-ietf-avt-rtp-midi-format

   Technical Summary

      These documents define the RTP Payload format for MIDI (Musical
      Instrument Digital Interface), and additional guidelines on
      implementation specifically concerning the timing of reception and
      transmission for best performance in different applications.  MIDI
      is a real-time media, which however is brittle to losses and
      errors.  Therefore the RTP payload format defines recovery
      journals as a way of avoiding persistent audible errors, and
      discusses congestion control handling for these journals.

      The RTP payload for MIDI encodes the broad range of MIDI commands.
      The format is suitable for interactive applications (such as
      network musical performance) and content-delivery (such as file
      streaming).

   Working Group Summary

      There is consensus in the WG to publish these documents.

   Document Quality

      This RTP Payload format has been implemented during the
      development of the specification and successfully tested over an
      IP network between two remote sites, thus showing that the
      technical solution is successfully working.  It has been reviewed
      by the MIDI Manufacturers Association and their comments have been

Levkowetz, et al.        Expires April 25, 2007                [Page 18]

Internet-Draft            Document Shepherding              October 2006

      addressed.  Allison Mankin reviewed the document for the IESG,
      including a careful review with the editor of the media types, in
      parallel with ietf-types list review requested on 2006-01-08,
      which raised no issues.

      Magnus Westerlund and Colin Perkins jointly shepherded these
      documents.

A.2.  Example Document Announcement Write-Up for
      draft-ietf-imss-ip-over-fibre-channel

   Technical Summary

      This document specifies the encapsulation of IPv6, IPv4 and ARP
      packets over Fibre Channel.  This document also specifies the
      methods for forming IPv6 link-local addresses and statelessly
      autoconfigured IPv6 addresses on Fibre Channel networks, and a
      mechanism to perform IPv4 address resolution over Fibre Channel
      networks.  This document (when published as RFC) obsoletes RFC2625
      and RFC3831.

   Working Group Summary

      This document has been reviewed by Fibre Channel experts in
      Technical Committee T11 (Fibre Channel standards organization) in
      addition to members of the IMSS WG.  There is solid support for
      this document both in the WG and from T11.

   Document Quality

      This document replaces and consolidates two separate RFCs on IPv4
      over Fibre Channel (RFC 2625) and IPv6 over Fibre Channel (RFC
      3831).  Most of its technical content is unchanged from those
      RFCs.  The technical changes that have been made are primarily
      based on implementation experience.

      The protocol has been reviewed for the IESG by David L. Black (WG
      chair).

      Also Bert Wijnen has reviewed this document for the IESG.

      In addition, Brian Haberman has done a review for the INT Area as
      requested by WG-chair (David Black) via Margaret Wasserman.

Levkowetz, et al.        Expires April 25, 2007                [Page 19]

Internet-Draft            Document Shepherding              October 2006

Appendix B.  Working Documents

   (This section should be removed by the RFC editor before
   publication.)

   The current working documents for this document are available at this
   web site:

   http://tools.ietf.org/wg/proto/
   draft-ietf-proto-wgchair-doc-shepherding/

Authors' Addresses

   Henrik Levkowetz
   Torsgatan 71
   Stockholm  S-113 37
   Sweden

   Phone: +46 708 32 16 08
   Email: [email-masked]

   David Meyer
   1225 Kincaid St
   Eugene, OR  97403
   USA

   Phone: +1 541 346 1747
   Email: [email-masked]

   Lars Eggert
   NEC Network Laboratories
   Kurfuerstenanlage 36
   Heidelberg  69115
   Germany

   Phone: +49 6221 4342 143
   Fax:   +49 6221 4342 155
   Email: [email-masked]
   URI:   http://www.netlab.nec.de/

Levkowetz, et al.        Expires April 25, 2007                [Page 20]

Internet-Draft            Document Shepherding              October 2006

   Allison Mankin

   Phone: +1-301-728-7199
   Email: [email-masked]
   URI:   http://www.psg.com/~mankin

Levkowetz, et al.        Expires April 25, 2007                [Page 21]

Internet-Draft            Document Shepherding              October 2006

Full Copyright Statement

   Copyright (C) The Internet Society (2006).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   [email-masked].

Acknowledgment

   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).

Levkowetz, et al.        Expires April 25, 2007                [Page 22]


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

---

From: Brian E Carpenter <[email-masked]>
Date: Mon, 23 Oct 2006 16:35:17 +0200

Thanks Allison. I will look at this asap but I'm on travel/in meetings
this week.

     Brian