RFC 4858

Document Shepherding from Working Group Last Call to Publication

📅 published May 2007, from ietf

RFC 4858 🎀 Document Shepherding from Working Group Last Call to Publication

Okay bestie, so this is RFC 4858 💖, and its title is "Document Shepherding from Working Group Last Call to Publication." It's an Informational RFC from May 2007 🦋. The four authors are H. Levkowetz (Ericsson), D. Meyer (Cisco/University of Oregon), L. Eggert (Nokia), and A. Mankin. The title block doesn't list anything it obsoletes or updates ✨.

Status of This Memo

This memo gives info to the Internet community, and it does not specify an Internet standard of any kind 🧚. You can distribute it freely, no restrictions.

Copyright Notice

The copyright line is Copyright (C) The IETF Trust (2007). 💅

Abstract

This doc is all about methodologies built to level up and streamline how IETF documents flow through processing 🔥. It lays out procedures where a working group chair or secretary acts as the main Document Shepherd for a document that's been sent to the IESG for publication. Before this, the Area Director for the working group was the one who usually did the shepherding job 👑.

1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  4
3.  Process Description  . . . . . . . . . . . . . . . . . . . . .  4
  3.1.  Document Shepherd Write-Up . . . . . . . . . . . . . . . .  5
  3.2.  Document Shepherding during AD Evaluation  . . . . . . . .  9
  3.3.  Document Shepherding during IESG Evaluation  . . . . . . . 10
4.  Shepherding the Document's IANA Actions  . . . . . . . . . . . 13
5.  Document Shepherding after IESG Approval . . . . . . . . . . . 14
6.  When Not to Use the Document Shepherding Process . . . . . . . 15
7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 16
8.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 16
9.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 16
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17
  10.1. Normative References . . . . . . . . . . . . . . . . . . . 17
  10.2. 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

1. Introduction ✨

Back in early 2004, the IESG ran a bunch of experiments to see whether any of the proposed changes to the IETF document flow would actually make things better, in terms of throughput and quality 🧪. One of them was called the "PROTO process" or just "PROTO." The name is a "PROcess and TOols" joke, since the team behind it was literally called PROTO [PROTO] 😭. Their goal was to get working group chairs or secretaries way more involved in their documents' approval life cycle. Specifically, PROTO focused on the stretch that happens after the working group and document editor forward a doc to the IESG for publication 💜.

By the end of 2004, the IESG had looked at the data from several pilot projects that ran all year and decided the PROTO methods were worth it. So they adopted the PROTO process for all documents and working groups 🎉. This RFC is the one that describes how that process works.

PROTO puts the working group chair or secretary in the driver's seat as the primary Document Shepherd. The big point of the shepherding process is to speed up document processing and improve quality by creating a partnership between the Responsible Area Director and the Document Shepherd 🤝. The partnership gives the Document Shepherd more power, and it also takes a chunk of follow-up work off the Responsible Area Director's plate. That matters because the Responsible Area Director has tens, or many tens, of documents to track, while the Document Shepherd usually has just a few at a time 🌸. Pushing the responsibility down to the working group level means more attention and faster responses. Honestly so smart.

So the shepherding process covers follow-up work at every stage after Working Group Last Call. That means AD Evaluation, IESG Evaluation, and the post-approval processing done by IANA and the RFC Editor 🔥. During all of those stages, the Document Shepherd is responsible for tracking and following up on feedback about the document from every relevant party.

The Document Shepherd is usually one of the chairs of the working group that produced the document 👑. The chairs can also decide, in consultation with the Responsible Area Director, to appoint the working group secretary as the responsible Document Shepherd instead 🦋.

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 read as described in BCP 14, RFC 2119 [RFC2119] 🧚.

3. Process Description 🌈

The shepherding process has the following tasks:

Writing the Document Shepherd Write-Up that goes along with a document when it's forwarded to the IESG and publication is requested, as described in Section 3.1 📝.
During AD Evaluation 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 🗣️.
During an IETF Last Call, if one is done for the shepherded document, following up on community feedback and review comments 📬.
During IESG Evaluation, following up on all IESG feedback ("DISCUSS" and "COMMENT" items) about the shepherded document, as described in Section 3.3 🔍.
Following up on IANA and RFC Editor requests, as described in Section 4 and Section 5 🫶.

The shepherd must keep the document moving forward and stay in touch with everyone who reviews or comments on it 💖. The shepherd must get the working group's consensus before any substantive changes get proposed. The shepherd is the leader for the document and for the working group, and keeps a critical, technical eye on things 🧠. Basically, the Document Shepherd keeps caring for a shepherded document after it leaves the working group, the same way they did while they were responsible for it inside the working group 🥹.

Before any shepherding happens, a single Document Shepherd MUST be identified for the document. That person gets named in the Document Shepherd Write-Up ✨. Often the chairs and the Responsible Area Director will decide that the working group will adopt the PROTO process for all of its future documents. After that call is made, the chairs, in consultation with the Responsible Area Director, pick who should be Document Shepherd for each document 🎀. Usually that's one of the working group's chairs by default. The chairs MAY also, in consultation with the Responsible Area Director, appoint the working group secretary as Document Shepherd for a given document 💜. The Document Shepherd SHOULD NOT be an editor of the shepherded document 🙈.

The plan is that one person fills the Document Shepherd role for the entire shepherding process 🦋. Still, the role can get reassigned to different people during a document's lifetime 🌸. The chairs and the Responsible Area Director are in charge of spotting when that's needed. Then they consult and appoint a new Document Shepherd 💅.

Finally, the document shepherding process only applies to documents that come out of a working group. It does not apply to documents from anywhere else 🚫. Section 6 also covers other situations where the shepherding process doesn't apply 📖.

🙈 Heads up: the shepherd and the Document Shepherd Write-Up are the core of this whole process, so the Write-Up has to name exactly one person.

3.1. Document Shepherd Write-Up ✨

Okay so, when a working group decides a document is ready to head to the IESG for publication, the Document Shepherd gets the job of writing up a "Document Shepherd Write-Up" for it 📝

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 the full tea on the working group process behind this document. Yes, some of these questions can look a little repetitive, but they're built to pull out the stuff the Responsible Area Director really needs to know (and pointing to relevant entries in the WG archive is super helpful 🙌). The goal is to flag anything that came up in IETF meetings, on the mailing list, or in private communication that they should be aware of before IESG Evaluation of the shepherded document. Any significant issues in the questionnaire will probably lead to a follow-up discussion with the Responsible Area Director 👀

The second part is preparing the "Document Announcement Write-Up," which feeds into both the ballot for the IESG telechat and the eventual IETF-wide announcement message. Item (1.k) describes what goes into it 💌

Some examples of Document Announcement Write-Ups are in Appendix A, and there are tons more with subject lines like "Protocol Action" and "Document Action" in the IETF-announce mailing list archive 📚

The starting template for the Document Shepherd Write-Up is below, but it's going to keep changing over time. The latest version lives in the IESG section of the IETF web site 🌐

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

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

(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, maybe they're uncomfortable with certain parts of the document, or have concerns about whether there really is a need for it. In any case, if the WG has discussed those issues and has indicated that it still wants to advance the document, detail those concerns here. Has an IPR disclosure related to this document been filed? If so, please include a reference to the disclosure and summarize the WG discussion and conclusion on this issue. ⚖️

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

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

(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 the formal review criteria it needs to, such as the MIB Doctor, media type, and URI type reviews? If the document does not already indicate its intended status at the top of the first page, please indicate the intended status here. ✅

(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 completing them? 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's IANA Considerations 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 suggest a reasonable name for the new registry? See [RFC2434]. If the document describes an Expert Review process, has the Document Shepherd conferred with the Responsible Area Director so that the IESG can appoint the needed Expert during IESG Evaluation? 🗂️

(1.j) Has the Document Shepherd verified that the sections of the document 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 one. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections: 📣

Technical Summary Relevant content can often be found in the abstract and/or introduction of the document. If not, that may be a sign that there are deficiencies in the abstract or introduction. 💡

Working Group Summary Was there anything in the WG process worth noting? For example, was there controversy about particular points, or were there decisions where the consensus was especially 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 who deserve special mention for 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? If the document requires IANA expert(s), insert 'The IANA Expert(s) for the registries in this document are <TO BE ADDED BY THE AD>.' 👑

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, may lead to possible appeals, or is personal 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 ID 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 make sure they're 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 for these parties to make sure they include the Document Shepherd, but hopefully automated tools will one day make sure Document Shepherds (and others) get the messages they need 🦋

The contact information for the Document Shepherd also matters a lot to the Gen-ART team [GEN-ART], area directorates, and other review teams, so they know who to address reviews to, alongside the Responsible Area Director 🧚

3.2. Document Shepherding during AD Evaluation ✨

okay so this is the AD Evaluation part, and it's giving very structured group project energy 💅 here are the steps, in order:

(2.a) The Responsible Area Director reads, evaluates, and comments on the document, just like they would if the document shepherding process weren't being used 📖 If the Responsible Area Director decides the document is ready for IESG Evaluation, they tell the Document Shepherd, and the process keeps going as described in Section 3.3 🦋

(2.b) If the Responsible Area Director finds issues that must be fixed before IESG Evaluation can start, they send a full evaluation to the Document Shepherd and SHOULD also put the review into the ID Tracker 🎀

(2.c) The Document Shepherd reads the AD Evaluation comments and makes SURE every single one is understood, so they can follow up with the editors and the working group 🧐 If something is unclear about what's being asked, this SHOULD be sorted out 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, so there's a permanent record of everything 📝 It is RECOMMENDED that the Document Shepherd ask the editors for an estimate of when the changes will be done and when a revised document can be expected 🌸 Working groups that use issue tracking SHOULD also log the issues (and eventually how they got resolved) in their issue tracker 🍓

(2.e) While the editors are writing the revised document that addresses the AD Evaluation comments, it is RECOMMENDED that they keep a list showing how each comment was handled and what the new text says 🫶 It is RECOMMENDED that this list gets forwarded to the Responsible Area Director along with the revised document ✨

(2.f) If the editors or the working group disagree with a comment from the Responsible Area Director, or they already thought about the issue and dismissed it, the Document Shepherd MUST sort it out with the Responsible Area Director before a revised document can be submitted 🔥 no skipping this one bestie

(2.g) The Document Shepherd keeps going back and forth with the editors (and the working group, if needed) until every outstanding issue is resolved and a revised document exists 🔄 At that point, the Document Shepherd tells the Responsible Area Director and hands over the revised document, the summary of issues, and the resulting text changes 🎁

(2.h) The Responsible Area Director checks that the issues they found during AD Evaluation are actually fixed in the revised version, by starting the process in this section over at step (2.a) 👑

(2.i) If the document went through an IETF Last Call and the AD concludes that significant issues came up during the Last Call, then steps (2.b) through (2.h) need to be applied to those Last Call issues too 🌈 This means the Responsible Area Director has to share those Last Call issues that were only sent to the IESG with the Document Shepherd 🙈

3.3. Document Shepherding during IESG Evaluation 💅

okay so during IESG Evaluation, ADs can bring up two kinds of remarks about a document: DISCUSS items and COMMENT items ✨ A DISCUSS blocks the document's approval process until it's resolved, but a COMMENT does not 🚫 This section walks through the steps a Document Shepherd takes to resolve any DISCUSS and COMMENT items raised against a shepherded document during IESG Evaluation 🦋

Sometimes DISCUSS and COMMENT items are written in a way that makes their intent unclear 😭 In these cases, the Document Shepherd SHOULD start a discussion with the ADs who raised the items to clarify what they meant, and keep the Responsible Area Director in the loop 🫶 If this doesn't clear things up, the Responsible Area Director may need to work toward 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, sent 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 start working on resolving the DISCUSS and COMMENT items with the ADs who raised them, keeping the Responsible Area Director copied on the email exchange so they can back everything up during the conference call 💜 When dealing with directorate reviews, the Document Shepherd MUST involve the ADs that those directorates report to, so those ADs consider the review comments that need resolving 👑

(3.b) Right after the conference call, when the document moves from the "IESG Evaluation" state to one of the states that need Document Shepherd action, like "IESG Evaluation: Revised ID Needed" or "IESG Evaluation: AD Followup", the Document Shepherd will get an email 📩 An "AD Followup" state usually means the Responsible Area Director is hoping a resolution is possible through more discussion or, more often, through a small set of changes as "Notes to the RFC Editor" 🎀

Note that there may be very exceptional cases where DISCUSS items get registered after an IESG conference call 👀 In these cases, the AD who raised the DISCUSS MUST notify the Document Shepherd about it 🔔 (The notification facility in the ID Tracker is super handy for this, and also for cases where the DISCUSS and COMMENT items get updated after they've been partially resolved 🍓)

(3.c) The Document Shepherd then queries the ID Tracker to collect the remaining DISCUSS and COMMENT items raised against the document 🔍 They analyze these items and start contact with the ADs who placed them 💬 The Responsible Area Director MUST be copied on all correspondence related to active DISCUSS or COMMENT items 📋 This doesn't put the Responsible Area Director in the critical path to a resolution, but should keep them 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 the DISCUSS and COMMENT items and builds a consistent interpretation of the comments 🧩 This step is pretty similar to a lot of what's in Section 3.2 🌈

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

(3.e) The Document Shepherd then tells the document editors and the working group about the DISCUSS and COMMENT items, and flags any changes that built up during IESG processing, like "Notes to the RFC Editor" 📣 If any changes are substantive, the Document Shepherd, in consultation with the Responsible Area Director (just like at other stages), MUST confirm working group consensus or sometimes even IETF consensus 🗳️

(3.f) After the editors resolve the DISCUSS and COMMENT items, the Document Shepherd reviews the new version of the document, which will be a revised document, a set of "Notes to the RFC Editor", or both 🔎 They use their technical expertise to make sure every raised DISCUSS and COMMENT issue is actually resolved 🧠

Note that the Document Shepherd MAY also suggest resolutions to DISCUSS and COMMENT items, enter them into an issue tracker, or take other steps to streamline how the evaluation comments get resolved 💡 It's super important to resolve the comments in a timely way, while the discussion is still fresh for everyone involved ⏰

(3.g) When the Document Shepherd is satisfied that the revised document addresses the evaluation comments, they tell the Responsible Area Director and the ADs who raised the DISCUSS and COMMENT items about the resolution 🥳

(3.h) Each AD who raised a DISCUSS checks whether the communicated resolution addresses their items ✅ If it does, the AD clears the DISCUSS 🙌 If it doesn't, the AD tells the Document Shepherd and adds information to the ID Tracker explaining why the DISCUSS wasn't resolved 😤 The Document Shepherd then lets the working group know 📢 (COMMENT items don't need to be checked and cleared, since they don't block the document, but ADs are encouraged to do so 💖)

If a DISCUSS isn't resolved to the satisfaction of the AD who raised it or of the Responsible Area Director, there are two possibilities 🤔

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

(b) If no progress can be made on resolving the DISCUSS with the AD who raised it, even after repeated clarifications and discussions, the Responsible Area Director should take over the continued shepherding of the document 🫠 Such a situation may be a sign of bigger issues that the PROTO process was not designed to handle 🙈

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 they think the changes to the revised document are significant, there may be a new WG Last Call, or possibly a new IETF Last Call 🔁 The document goes through a whole new full IESG Evaluation process if there's a new IETF Last Call 🦋

4. Shepherding the Document's IANA Actions ✨

okay so IETF working group docs often have stuff that needs IANA to do something, like making a brand new registry or adding entries to an existing one 📚. Sometimes that happens after the IANA checks in with an IESG-appointed Expert. The Document Shepherd also has to keep track of certain IANA stuff the IESG needs to finish, like ratifying a designated Expert the IANA Considerations section asks for 👑. IANA processing can also come with a specific kind of Expert review, like checking proposed MIME media types on the designated ietf-types mailing list 💌.

IANA looks at IETF docs and asks for responses at any or all of these moments: when IETF Last Call is happening, during the IESG Evaluation of the document, and when IANA updates its web-based registry for the document. That last one is usually after IESG approval, but not always 🌸. You can find more about the IANA process and how it works with the IETF in [RFC2434].

RFC 2434 is currently being revised as [RFC2434bis], and those updates are and will be super valuable to the Document Shepherd 🧚. Also, the Document Shepherd MUST figure out (by reviewing things individually and talking to people) what the most recent and most relevant IANA info and guidance is for their document 🔍. That could be the overall guidance, or outside documents in their own area or other areas. An example of an outside document is [RFC4020] 🎀.

Whenever an IANA request shows up, at any phase of shepherding, the IANA requester MUST make sure that both the Document Shepherd and the Responsible Area Director get it 📬. The Document Shepherd is responsible for replying as fast as possible ⚡. If a request raises any possible concerns, they should talk it through with the working group. The Document Shepherd and the Responsible Area Director can also decide together that an IANA request means a change that needs extra review or approval 🫶.

Generally, the Document Shepherd makes sure the IANA process finishes, checks that the registry is correct and that the IANA Matrix (http://www.iana.org/numbers.html) is complete and consistent, and fixes things when they go sideways 🛠️. When IANA processing is all done, the Document Shepherd should make sure the RFC Editor has acknowledged that IANA is finished. In other words, the handoff has happened 🤝.

Honestly, shepherding IANA actions gets overlooked a lot, but it's just as important to coordinate and manage as every other review the Document Shepherd handles 💅. Just like those, the Document Shepherd helps a ton with the quality and timeliness of the document by being on top of and responsive to IANA requests 💖.

5. Document Shepherding after IESG Approval 🌈

So after the IESG Evaluation and resolution in Section 3.3, the IESG approves the document 🎉. The Responsible Area Director then uses the ID Tracker to ask for any last-minute changes to the Document Announcement Write-Up and to get it issued. The Document Shepherd might have some edits for the Responsible Area Director, like minor "Notes to the RFC Editor." This is the moment to check in with them and hand those over 📝.

The IESG approval announcement goes out to the general community and to the RFC Editor. From here, the Document Shepherd (the one named in the Announcement Write-Up) keeps shepherding the document through its technical publication 🚀. The RFC Editor currently sends a bunch of different kinds of requests to the authors, the Document Shepherd, and the Responsible Area Director. The Document Shepherd SHOULD lead on answering the RFC Editor and keep shepherding the document through the post-approval period until it's published 🦋.

The RFC Editor request types include editorial queries about dangling or missing informative and normative citations. Good shepherding should catch these earlier, but they still happen 🙈. They also include requests for the document source (like XML or nroff), now and then some technical comments, and copy-edits that the authors have to review and look at very closely (that's AUTH48) 🔍. For the copy-edits, the Document Shepherd SHOULD lead in checking that the edits never messed with a consensus wording the working group came up with. They SHOULD also speed things up by getting multiple coauthors involved 👯. The Document Shepherd also talks with the Responsible Area Director about reviewing proposed post-approval changes from any author. Those changes might need Area Director approval, and they often have to go back to the working group for consent if it wasn't a full consensus procedure 🧐.

Just like in every other phase, the Document Shepherd brings attentiveness and timeliness by being the informed representative of the document. They help it move forward and keep it intact 💜.

6. When Not to Use the Document Shepherding Process 🙅‍♀️

As mentioned in Section 3, the Document Shepherd SHOULD NOT be an editor of the document they're shepherding. If you can't avoid that by making another working group chair or secretary the Document Shepherd, then the document shepherding process SHOULD NOT be used 🚫. There are a few other situations where the document shepherding process SHOULD NOT be used either. These include:

Cases where the Document Shepherd is the primary author or editor of a large percentage of the documents the working group produces.
Cases where the Responsible Area Director expects communication difficulties with the Document Shepherd. That could come from past experience, strong views the Document Shepherd has stated, or other issues 😬.
Cases where the working group itself is very old, losing energy, or winding down. In other words, cases where starting new processes or procedures wouldn't be productive 🥀.

Also, note that other cases exist where using the document shepherding process might not be productive. The final call on whether to use the document shepherding process is left to the Responsible Area Director 👑. If the document shepherding process isn't used, the Responsible Area Director acts as the Document Shepherd, following the existing procedures for shepherding by Area Directors 🌸.

7. Security Considerations 🔐

This document specifies a change to IETF document-processing procedures. As such, it neither raises nor considers protocol-specific security issues 💀. (Still, just because it's about procedures doesn't mean it's not important, so keep it in mind.)

8. IANA Considerations 🧚

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

9. Acknowledgments 💖

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

The Document Shepherd Write-Up started as an idea from John Klensin. Thomas Narten and Margaret Wasserman implemented it for the entire Internet Area, and their template is the basis of the version used today 👑.

Colin Perkins wrote the original Document Announcement Write-Up for draft-ietf-avt-rtp-midi-format, which is included in Appendix A.1. David Black wrote the original Document Announcement Write-Up for draft-ietf-imss-ip-over-fibre-channel, which is included in Appendix A.2. Both original announcements have been modified to reflect changes to the Document Announcement Write-Up template since they were written 🎀.

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

10. References 📚

10.1. Normative References

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

10.2. Informative References

[RFC4020] Kompella, K. and A. Zinin, "Early IANA Allocation of Standards Track Code Points", BCP 100, RFC 4020, February 2005.
[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 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.
[RFC2434bis] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", Work in Progress, March 2007.
[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. Example Document Announcement Write-Ups 🦋

This appendix has two examples of Document Announcement Write-Ups. Tons more examples with Subject lines like "Protocol Action" and "Document Action" are 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), plus extra guidelines on implementation, specifically about the timing of reception and transmission for the best performance in different applications 🎹. MIDI is real-time media, but it's brittle to losses and errors 😭. So the RTP payload format defines recovery journals as a way to avoid persistent audible errors, and it talks about how to handle congestion control for those journals ✨.

The RTP payload for MIDI encodes the broad range of MIDI commands 🎶. The format works for interactive applications (like network musical performance) and for content delivery (like file streaming) 🌸.

Working Group Summary

There is consensus in the WG to publish these documents 🫶.

Document Quality

This RTP Payload format was implemented while the specification was being developed, and it was successfully tested over an IP network between two remote sites. That shows the technical solution really works 🔥. It was reviewed by the MIDI Manufacturers Association, and their comments were addressed 💅.

Personnel

Magnus Westerlund and Colin Perkins jointly shepherded this document 🧚. Allison Mankin reviewed the document for the IESG, including a careful review with the editor of the media types. This happened in parallel with the ietf-types list review requested on 2006-01-08, which raised no issues 🌈.

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

Technical Summary 💖

This document is all about getting IPv6, IPv4, and ARP packets to ride over Fibre Channel 🚄. It also explains how to form IPv6 link-local addresses and statelessly autoconfigured IPv6 addresses on Fibre Channel networks, and it adds a mechanism for IPv4 address resolution over those networks 🧚. When this gets published as an RFC, it obsoletes RFC2625 and RFC3831 💅.

Working Group Summary 🫶

The Fibre Channel experts in Technical Committee T11 (the Fibre Channel standards organization) reviewed this document, and so did the members of the IMSS WG 👑. Honestly the support is solid, from the WG and from T11 too 🔥.

Document Quality 🌸

This document replaces and combines two separate RFCs: one on IPv4 over Fibre Channel (RFC 2625) and one on IPv6 over Fibre Channel (RFC 3831) 🎀. Most of the technical content is unchanged from those RFCs ✨. The technical changes that did happen are mostly based on implementation experience, which is so important 🙈.

Personnel 🦋

David L. Black (the WG chair) reviewed the protocol for the IESG 💜. Bert Wijnen also reviewed this document for the IESG 🌈. And Brian Haberman did a review for the INT Area, because the WG chair (David Black) asked for it via Margaret Wasserman 🍓.

Authors' Addresses 🌈

Henrik Levkowetz
Torsgatan 71
Stockholm  S-113 37
Sweden

Phone: +46 708 32 16 08
EMail: henrik@levkowetz.com


David Meyer
1225 Kincaid St
Eugene, OR  97403
USA

Phone: +1 541 346 1747
EMail: dmm@1-4-5.net


Lars Eggert
Nokia Research Center
P.O. Box 407
Nokia Group  00045
Finland

Phone: +49 50 48 24461
EMail: lars.eggert@nokia.com
URI:   http://research.nokia.com/people/lars_eggert


Allison Mankin

Phone: +1-301-728-7199
EMail: mankin@psg.com
URI:   http://www.psg.com/~mankin

Full Copyright Statement ⭐

This document is subject to the rights, licenses, and restrictions in BCP 78. Apart from what BCP 78 says, the authors keep 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, THE IETF TRUST 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 doesn't take a side on whether any Intellectual Property Rights or other rights that someone might claim over the technology in this document are valid or how far they reach 🙈. It also doesn't say whether a license for those rights is available, and it hasn't independently gone hunting for any such rights either 🔍. If you want the procedures for rights in RFC documents, check out BCP 78 and BCP 79 📚.

Copies of IPR disclosures sent to the IETF Secretariat are available, along with any assurances of licenses to be made available. You can also get the result of any attempt to obtain a general license or permission for implementers or users to use these proprietary rights. Just look in the IETF online IPR repository at http://www.ietf.org/ipr 💌.

The IETF invites anyone who is interested to let it know about any copyrights, patents, patent applications, or other proprietary rights that might cover technology needed to implement this standard 🫶. Send that information to the IETF at ietf-ipr@ietf.org 💖.

Acknowledgement 💐

Funding for the RFC Editor function is currently provided by the Internet Society 🙌.

📦 where this page comes from

ietf: rfc4858 2007-05
💖 girlified by claude-haiku-5-5 on 2026-10-17: a language model's rewrite of the original, under its terms