Document Shepherding from Working Group Last Call to Publication

The document shepherding process consists of the following tasks: Providing the Document Shepherd Write-Up accompanying a document that is forwarded to the IESG when publication is requested, as described in . 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 . During IESG evaluation, following up on all IESG feedback ("DISCUSS" and "COMMENT" items) related to the shepherded document, as described in . 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 similar to how he or she has done while responsible for the document in a working group. Before any document shepherding takes place, a single Document Shepherd MUST be identified for a document. Frequently, the chairs and the 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. 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 situation when this may become necessary, and they 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, discusses other instances in which the document shepherding process does not apply.

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.j) 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.k) describes the elements of the Document Announcement Write-Up. 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 , and there are many more examples with subject lines such as "Protocol Action" and "Document Action" in the IETF-announce mailing list archive. 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? 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? 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? 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. 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? 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.) 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 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 ? If so, list these downward references to support the Area Director in the Last Call procedure for them . 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 if suggested a reasonable name for the new registry? See . 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? 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. The approval announcement contains the following sections: 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. 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? 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? 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 iesg-secretary@ietf.org 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. The Document Shepherd Write-Up is entered into the ID Tracker 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. 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. This information is also important for the IETF Chair's Gen-ART Directorate and other directorates, so they can know where to address reviews to, in addition to the Responsible Area Director.

The steps for document shepherding during AD Evaluation are as follows: 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 . 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. 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. 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. 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. 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. 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. 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).

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. 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. 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.) 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.c) | ------------> | (3.d) | +-------+ Comments +-------+ Comments +-------+ collected /|\ | understood | | | | Comments not fully understood | | (Further AD/Document Shepherd | | discussion required) +---+ ]]> 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 .

| (3.d) | +-------+ Consistent +-------+ /|\ interpretation | | | Further AD/Document Shepherd | | discussion required +--------------------------+ ]]> 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." 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. 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. Each AD that had raised a DISCUSS checks whether the communicated resolution addresses their DISCUSS 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: The process returns to step (3.d), or 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 and referred to in . The Document Shepherd SHOULD also review the IESG's Discuss Criteria guidelines and discuss with the Responsible Area Director whether there might be considerations 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). 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, there may be a new WG last call. In the latter case, the document may go through a full IESG Evaluation process again.

draft-ietf-proto-wgchair-doc-shepherding-07.txt

draft-ietf-proto-wgchair-doc-shepherding.txt

PROTO Team A. Falk

Internet-Draft ISI

Intended status: Informational H. Levkowetz

Expires: December 25, 2006 Ericsson

Expires: April 20, 2007 Ericsson

D. Meyer

Cisco/University of Oregon

L. Eggert

NEC

A. Mankin

June 23, 2006

October 17, 2006

Document Shepherding From Working Group Last Call to IESG Approval

Document Shepherding from Working Group Last Call to Publication

draft-ietf-proto-wgchair-doc-shepherding-07

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

skipping to change at page 1, line 40

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 December 25, 2006.

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

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

submitted to the IESG for publication. Before this, the shepherding

submitted to the IESG for publication. Before this, the Area

role has traditionally been filled by the Area Director responsible

Director responsible for the working group has traditionally filled

for the working group.

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 authors, the working group, and the

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 similar to the way he or she has

cared for it while responsible for the document in a working group.

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 . . . . . . . . 8

3.2. Document Shepherding during AD Evaluation . . . . . . . . 9

3.3. Document Shepherding during IESG Evaluation . . . . . . . 10

4. When Not to Use the Document Shepherding Process . . . . . . . 12

4. Document Shepherding after IESG Approval . . . . . . . . . . . 13

5. Security Considerations . . . . . . . . . . . . . . . . . . . 13

5. When Not to Use the Document Shepherding Process . . . . . . . 13

6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13

6. Security Considerations . . . . . . . . . . . . . . . . . . . 14

7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 13

7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14

8. Informative References . . . . . . . . . . . . . . . . . . . . 14

8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14

Appendix A. Working Documents . . . . . . . . . . . . . . . . . . 14

9. Informative References . . . . . . . . . . . . . . . . . . . . 15

Appendix B. Example Document Announcement Write-Ups . . . . . . . 15

Appendix A. Example Document Announcement Write-Ups . . . . . . . 16

B.1. Example Document Announcement Write-Up for

A.1. Example Document Announcement Write-Up for

draft-ietf-avt-rtp-midi-format . . . . . . . . . . . . . . 15

draft-ietf-avt-rtp-midi-format . . . . . . . . . . . . . . 16

B.2. Example Document Announcement Write-Up for

A.2. Example Document Announcement Write-Up for

draft-ietf-imss-ip-over-fibre-channel . . . . . . . . . . 16

draft-ietf-imss-ip-over-fibre-channel . . . . . . . . . . 17

Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16

Appendix B. Working Documents . . . . . . . . . . . . . . . . . . 17

Intellectual Property and Copyright Statements . . . . . . . . . . 18

Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18

Intellectual Property and Copyright Statements . . . . . . . . . . 19

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

skipping to change at page 4, line 28

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

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 empowering 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.

Consequently, the document shepherding process includes follow-up

work during all document processing stages after Working Group Last

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 a working group

secretary as the responsible Document Shepherd.

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

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 4 describes those cases in which the

shepherding. Finally, Section 5 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 authors, the working

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 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 similar to how how he or she has

document during its post-WG lifetime similar to how he or she has

done while responsible for the document in a working group.

Before any document shepherding takes place, a single Document

Shepherd must be identified for a document. This is typically the

Shepherd MUST be identified for a document. Frequently, the chairs

chair of the working group that has produced a document. If the

and the Responsible Area Director will decide that the working group

working group has more than one chair, the chairs decide on who

will adopt the PROTO process for all their future documents. After

should act as Document Shepherd for a document. In consultation with

that decision, the chairs, in consultation with the Responsible Area

the Responsible Area Director, the chairs may also decide to appoint

Director, decide on who should act as Document Shepherd for any given

a working group secretary as Document Shepherd. The Document

document. This is typically and by default one of the chairs of the

Shepherd SHOULD NOT be an author of the shepherded document.

working group. In consultation with the Responsible Area Director,

the chairs MAY also decide to appoint the working group secretary as

Document Shepherd. 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 situation when this

may become necessary, and they 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 4 discusses other instances in which the document shepherding

Section 5 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.h below to give the Responsible Area

answers questions (1.a) to (1.j) 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 will be helpful). The goal here

relevant entries in the WG archive are helpful). The goal here is to

is to inform the Responsible Area Director about any issues that may

inform the Responsible Area Director about any issues that may have

have come up in IETF meetings, on the mailing list, or in private

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)

to the eventual IETF-wide announcement message. Item number (1.k)

describes the elements of the Document Announcement Write-Up. Some

describes the elements of the Document Announcement Write-Up.

examples of Document Announcement Write-Ups are included in

Appendix B, and there are many more examples with Subject lines such

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

skipping to change at page 7, line 4

skipping to change at page 7, line 21

(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 those issues have been discussed in the WG and the

event, if the WG has discussed those issues and has indicated

WG has indicated that it still wishes to advance the document,

that it still wishes to advance the document, detail those

detail those concerns here.

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 will

should be in a separate email because this questionnaire is

be entered into the ID Tracker.)

entered into the ID Tracker.)

(1.g) Has the Document Shepherd verified that the document satisfies

(1.g) Has the Document Shepherd personally verified that the

all ID nits? (See http://www.ietf.org/ID-Checklist.html and

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.

(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) The IESG approval announcement includes a Document

(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 if suggested a

reasonable name for the new registry? See

[I-D.narten-iana-considerations-rfc2434bis].

(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 Write-Up. 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.

skipping to change at page 8, line 17

skipping to change at page 8, line 49

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?

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? 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 iesg-secretary@ietf.org 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 there is information which may prove to be

mailing list. If the Document Shepherd feels that information which

sensitive, lead to possible appeals or is personal information that

may prove to be sensitive, lead to possible appeals or is personal

the Document Shepherd feels should be written up, it should be sent

information needs to be written up, it SHOULD be sent in direct email

in direct email to the Responsible Area Director, because the

to the Responsible Area Director, because the Document Shepherd

Document Shepherd Write-Up will be published openly in the tracker.

Write-Up is published openly in the tracker.

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. In addition to making life easier during

Change Notice To" field.

IESG Evaluation, this information is important for the IETF Chair's

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. This information is also important for the IETF Chair's

Gen-ART [GEN-ART] Directorate and other directorates, so they can

know where to address reviews to, 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.

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 authors and working

possible to follow up on them with the editors and working

group. If there is some uncertainty as to what is requested,

this must be resolved with the Responsible Area Director.

this SHOULD be resolved with the Responsible Area Director.

(2.d) The Document Shepherd sends the AD Evaluation comments to the

authors and to the working group mailing list, in order to

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 authors an

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

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

authors keep a list showing how each comment was addressed and

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.

(2.f) In the event that the authors or working group disagrees with

(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 authors (and working

(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).

skipping to change at page 10, line 23

skipping to change at page 11, line 14

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 one or more ADs and also emailed copies of DISCUSS

on behalf of one or more ADs and also emailed copies of

and COMMENT items entered into the ID Tracker. The Document

DISCUSS and COMMENT items entered into the ID Tracker. The

Shepherd SHOULD immediately begin to work on resolving DISCUSS

Document Shepherd SHOULD immediately begin to work on

and COMMENT items with the ADs who have raised them, keeping

resolving DISCUSS and COMMENT items with the ADs who have

the Responsible Area Director copied on the email exchange, so

raised them, keeping the Responsible Area Director copied on

that he or she is able support the the activity during the

the email exchange, so that he or she is able to support the

conference call. When dealing with directorate reviews, the

the activity during the conference call. When dealing with

Document Shepherd MUST involve the ADs to whom these

directorate reviews, the Document Shepherd MUST involve the

directorates report to ensure that these ADs consider the

ADs to whom these directorates report to ensure that these ADs

review comments that need resolving.

consider the review comments that need resolving.

(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."

skipping to change at page 11, line 25

skipping to change at page 12, line 16

| (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 a consistent

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.

+-------+ +-------+

| (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 authors and the working group.

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."

(3.f) After the authors resolve the DISCUSS and COMMENT items, the

(3.f) After the editors resolve the DISCUSS and COMMENT items, the

Document Shepherd reviews the resulting revised document,

Document Shepherd reviews the resulting new version of the

using his or her technical expertise to ensure that all raised

document, which will be a revised document, a set of "Notes to

DISCUSS and COMMENT issues have been resolved.

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

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.

skipping to change at page 12, line 47

skipping to change at page 13, line 42

Once the process above has cleared all DISCUSS items, document

shepherding continues with step (3.i).

(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,

there may be a new WG last call. In the latter case, the

document may go through a full IESG Evaluation process again.

4. When Not to Use the Document Shepherding Process

4. Document Shepherding after IESG Approval

5. When Not to Use the Document Shepherding Process

As mentioned in Section 3, the Document Shepherd SHOULD NOT be an

author of the shepherded document. If this cannot be avoided by

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

skipping to change at page 13, line 28

skipping to change at page 14, line 26

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.

5. Security Considerations

6. Security Considerations

This document specifies a change to IETF document processing

This document specifies a change to IETF document-processing

procedures. As such, it neither raises nor considers protocol-

specific security issues.

6. IANA Considerations

7. IANA Considerations

This document creates no new requirements on IANA namespaces or other

IANA requirements.

7. Acknowledgments

8. Acknowledgments

This document is the product of PROTO team, which includes the

authors as well as Bill Fenner, Barbara Fuller, and Margaret

Wasserman.

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 B.1. David Black

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 B.2.

draft-ietf-imss-ip-over-fibre-channel included in Appendix A.2.

8. Informative References

Frank Ellermann and Olafur Guomundsson have suggested improvements to

the document during IETF Last Call.

9. 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]

"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. Working Documents

Appendix A. Example Document Announcement Write-Ups

(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/

Appendix B. 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.

B.1. Example Document Announcement Write-Up for

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

skipping to change at page 16, line 5

skipping to change at page 17, line 5

technical solution is successfully working. It has been reviewed

by the MIDI Manufacturers Association and their comments have been

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.

B.2. Example Document Announcement Write-Up for

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

skipping to change at page 16, line 41

skipping to change at page 17, line 41

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.

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

Aaron Falk

Email: falk@isi.edu

Henrik Levkowetz

Torsgatan 71

Stockholm S-113 37

Sweden

Phone: +46 708 32 16 08

Email: henrik@levkowetz.com

David Meyer

1225 Kincaid St

End of changes. 55 change blocks.

109 lines changed or deleted

174 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/