idnits 2.17.00 (12 Aug 2021) /tmp/idnits58038/draft-leiba-extended-doc-shepherd-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 4, 2012) is 3484 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Leiba 3 Internet-Draft Huawei Technologies 4 Intended status: Informational November 4, 2012 5 Expires: May 8, 2013 7 Document Shepherding Throughout a Document's Lifecycle 8 draft-leiba-extended-doc-shepherd-01 10 Abstract 12 RFC 4858 talks about "Document Shepherding from Working Group Last 13 Call to Publication". There's a significant part of a document's 14 life that happens before working group last call, starting, really, 15 at the time a working group begins discussing a version of the idea 16 that's been posted as an individual draft. It seems reasonable and 17 helpful to begin shepherding when there's a call for adoption as a 18 working group document, and this document gives one Area Director's 19 view of how that extended shepherding function might work, and what 20 tasks might be involved throughout the document's lifecycle. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on May 8, 2013. 39 Copyright Notice 41 Copyright (c) 2012 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . . 4 59 2. The Document Shepherd as a "Function" . . . . . . . . . . . 5 61 3. Stages in a Document's Lifecycle . . . . . . . . . . . . . . 6 62 3.1. Stage: Call for Adoption . . . . . . . . . . . . . . . . . . 6 63 3.2. Stage: Working Group Document . . . . . . . . . . . . . . . 8 64 3.3. Stage: Working Group Last Call . . . . . . . . . . . . . . . 10 65 3.4. Stage: Shepherd Writeup Underway . . . . . . . . . . . . . . 11 66 3.5. Stage: AD Review . . . . . . . . . . . . . . . . . . . . . . 13 67 3.6. Stage: IETF Last Call . . . . . . . . . . . . . . . . . . . 14 68 3.7. Stage: Waiting for AD Go-Ahead . . . . . . . . . . . . . . . 15 69 3.8. Stage: IESG Evaluation . . . . . . . . . . . . . . . . . . . 15 70 3.9. Stage: Approved by the IESG . . . . . . . . . . . . . . . . 17 71 3.10. Stage: In RFC Editor Queue . . . . . . . . . . . . . . . . . 17 72 3.11. Stage: AUTH48 . . . . . . . . . . . . . . . . . . . . . . . 18 73 3.12. Stage: Published . . . . . . . . . . . . . . . . . . . . . . 19 75 4. Some Final Notes . . . . . . . . . . . . . . . . . . . . . . 20 77 5. Security Considerations . . . . . . . . . . . . . . . . . . 21 79 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . 22 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 82 7.1. Normative References . . . . . . . . . . . . . . . . . . . . 23 83 7.2. Informative References . . . . . . . . . . . . . . . . . . . 23 85 Author's Address . . . . . . . . . . . . . . . . . . . . . . 24 87 1. Introduction 89 RFC 4858 talks about "Document Shepherding from Working Group Last 90 Call to Publication" [RFC4858]. There's a significant part of a 91 document's life that happens before Working Group Last Call, 92 starting, really, at the time a working group begins discussing a 93 version of the idea that's been posted as an individual draft. It 94 seems reasonable and helpful to begin shepherding at the time there's 95 a call for adoption as a working group document, and this document 96 gives one Area Director's view of how that extended shepherding 97 function might work, and what tasks might be involved throughout the 98 document's lifecycle. 100 It has been very common to see documents -- including some that I 101 have authored, and some for which I have been the Responsible Chair 102 -- progress far too slowly, sometimes languishing for many months and 103 even for years due to neglect. Sometimes a working group will 104 intentionally set a document aside, put it on a back burner while it 105 works on more pressing things. But it's often *not* intentional, and 106 the document sits around because of lack of follow-through, waking up 107 occasionally when someone realizes that the last version has expired 108 and an IETF meeting is coming up soon. 110 We would really prefer to process documents efficiently, ensuring 111 that whatever happens is intentional: that documents are set aside 112 only when it makes sense to do so, and that active documents move 113 forward in the process, with someone assigned to make sure that 114 happens. 116 This document suggests specific tasks a Working Group Chair should be 117 doing or delegating in order to maintain forward progress, 118 accountability, and quality control on a working group document. It 119 adds to what's in RFC 4858, intending to extend it, not replace it. 120 Major extensions involve assigning a Shepherd and defining specific 121 tasks earlier in a document's life, and possibly delegating Document 122 Shepherd tasks to a Shepherd who is neither a Chair nor the Working 123 Group Secretary (consistent with the IESG Statement on Document 124 Shepherds [Stmt]). 126 By providing summaries in each section of the tasks expected at that 127 stage in the document's lifecycle, I hope to make this an easy 128 reference and checklist for Working Group Chairs and Document 129 Shepherds. 131 I also want to stress that the specific mechanism suggested here will 132 not be suitable for all working groups, all management models, and 133 all situations. While I think that it's still a good idea to have 134 the stages laid out and the tasks at each stage identified, not all 135 working groups will benefit from having a single document shepherd 136 designated at the start. Indeed, when a document is legitimately 137 years in the making, personnel may come and go and changes will be 138 necessary. A particular working group might be working only on one 139 document at a time, with all tasks shared between the chairs. 141 For these and other reasons, the suggestions herein are meant to be 142 adapted to specific situations to retain the underlying objective of 143 maintaining progress through active involvement. 145 1.1. Notational Conventions 147 Because this document is specifically one individual's thoughts on 148 this matter, it's worth pointing out that the document makes no 149 process changes and there is no normative language here. 151 I use Initial Capitals in some terms, such as "Document Shepherd", to 152 indicate that those terms represent formal roles in the management 153 model I'm describing. 155 2. The Document Shepherd as a "Function" 157 This document looks at the Document Shepherd as a "function", rather 158 than as a single person. The Document Shepherd Function has a set of 159 tasks that need to be performed, but the tasks do not all have to be 160 performed by one individual. 162 While, ultimately, it is the responsibility of the Working Group 163 Chairs to ensure that the shepherding tasks get done, the Chairs do 164 not have to do all those tasks by themselves. From Section 6.1 of 165 the Working Group Guidelines and Procedures [RFC2418]: 167 The Working Group Chair is concerned with making forward progress 168 through a fair and open process, and has wide discretion in the 169 conduct of WG business. The Chair must ensure that a number of 170 tasks are performed, either directly or by others assigned to the 171 tasks. 173 This document proposes an extended set of Document Shepherd tasks, 174 well beyond those covered in RFC 4858. In many cases it will be 175 reasonable to assign the entire Document Shepherd Function to one 176 person (to a Chair or to a non-chair delegate), but in many other 177 cases the Chairs will likely choose to delegate parts of that 178 function and keep other parts for themselves. In any case, the 179 Chairs remain responsible for the management of the working group; 180 they are whom the Area Director will come to if something goes wrong 181 or things fail to make progress. 183 As I talk, then, about what the "Document Shepherd" does, understand 184 that the individual doing each particular task will be the one 185 assigned that task as the work on a particular document is laid out. 186 When I say that the Shepherd should do a task in consultation with 187 the Chairs, that's automatically true when it's already a Chair who's 188 doing it. 190 And this bears repeating, so I will say it more than once here: 191 Nothing in this document is suggesting that the Working Group Chairs 192 abdicate any responsibility. They have the final responsibility for 193 managing each document's progress and for managing the working group 194 in general. Any Chair who chooses to delegate some of this 195 responsibility must still ensure that it's carried out properly. And 196 any Chair who does not feel comfortable delegating any of this should 197 not do so. 199 3. Stages in a Document's Lifecycle 201 From the time a working group is asked to take on a document as one 202 of its work items, the document will go through a number of stages: 204 1. Call for Adoption 205 2. Working Group Document 206 3. Working Group Last Call 207 4. Shepherd Writeup Underway 208 5. AD Review 209 6. IETF Last Call 210 7. Waiting for AD Go-Ahead 211 8. IESG Evaluation 212 9. Approved by the IESG 213 10. In RFC Editor Queue 214 11. AUTH48 215 12. Published 217 Through most of those stages steps will have to be taken, tasks will 218 need to be performed, to make sure the document moves forward, that 219 consensus is reached, that the right reviews are done, that updates 220 are made, that consensus still holds after significant changes, and 221 so on. That set of tasks comprises the Document Shepherd Function. 223 The following sections will discuss some of the tasks needed at each 224 stage, and will suggest how Working Group Chairs might handle those 225 tasks and their delegation -- how the Document Shepherd Function 226 might work. The details will vary, depending upon how each working 227 group is managed, but what follows should be a good example, and will 228 provide a basis for adaptation. And see also Section 3 of [RFC4858]. 230 3.1. Stage: Call for Adoption 232 At the point that the working group begins considering adoption of a 233 document, the Working Group Chairs have some decisions to make. This 234 is the time to choose a Responsible Chair for the document, much as 235 it will eventually have a Responsible Area Director later in its 236 life. The Responsible Chair will be the one who oversees the 237 Document Shepherd Function and has primary responsibility for making 238 sure that everything gets done. 240 The Responsible Chair should then (perhaps in consultation with the 241 other Chair(s), depending upon the Chairs' agreement about division 242 of work) decide how much of the Document Shepherd Function to handle 243 herself, and which pieces, if any, to delegate. Examples might be as 244 follows: 246 o The Responsible Chair will be the sole Document Shepherd. 248 o The Responsible Chair will be the Document Shepherd through the 249 end of the Working Group Document stage, and will appoint a non- 250 chair Shepherd during that stage to handle subsequent shepherding 251 tasks (similar to what's set out in RFC 4858). 253 o The Responsible Chair will appoint a non-chair Shepherd to handle 254 the early shepherding tasks, and the Responsible Chair will take 255 over the Document Shepherd tasks for Working Group Last Call and 256 beyond (the converse of the previous example). 258 o The Responsible Chair will appoint a non-chair Shepherd to handle 259 all shepherding tasks from start to end. The delegate will work 260 closely with the Responsible Chair, heavily supervised (perhaps 261 this is a training situation). 263 o The Responsible Chair will appoint a non-chair Shepherd to handle 264 all shepherding tasks from start to end. The delegate will report 265 to the Responsible Chair, and will be supervised at certain key 266 points. 268 o The Responsible Chair will appoint a non-chair Shepherd to handle 269 all shepherding tasks autonomously (perhaps for a very experienced 270 Shepherd, well trusted by the Chairs). 272 And so on... there may be many combinations, many levels of 273 supervision vs autonomy, many ways to divide the work. It's also 274 possible to delegate to more than one non-chair Shepherd at different 275 stages, though I don't think that's a good idea -- the continuity and 276 centralized responsibility of making it one other person (supervised 277 by one Responsible Chair) seems best. 279 Some Chairs may prefer to handle all tasks themselves, because, after 280 all, they remain responsible for their successful completion. Yet 281 there's a lot to be gained by delegating much of the work. 282 Delegating work and giving a degree of responsibility to relatively 283 more junior participants gets people more closely engaged with the 284 working group and with the IETF. Giving significant responsibility 285 can be an excellent training exercise, preparing participants to take 286 on future roles as Working Group Chairs. And in a busy working 287 group, offloading work from the Chairs to senior, experienced people 288 (perhaps former Chairs or former ADs) can prevent the Chairs from 289 being overcommitted, enabling the work to move forward much more 290 efficiently. 292 And, of course, a non-chair Shepherd can and should consult with the 293 Responsible Chair whenever she feels the need, and certainly whenever 294 issues arise of which the Chairs should be aware, or about which the 295 Shepherd needs advice or other help. 297 Once it is determined who will handle the Document Shepherd tasks, 298 the Shepherd needs to do the actual adoption process. The details 299 will vary based on how the particular working group is run, but a 300 typical process will start with posting a call for adoption to the 301 working group mailing list, pointing to the individual draft that's 302 being considered. There'll be a comment period for adoption 303 discussion, after which the Shepherd will, based on working group 304 discussion make a judgment and announce the result to the list. 306 Assuming that the document was adopted, the Chairs will appoint one 307 or more Editors for the working group version of the document (these 308 are often, but not always, the same people who wrote the individual 309 version, and the Chairs should put some thought into who the right 310 Editors should be), and will handle the datatracker updates (for 311 which Chair access is required). The Chairs should not forget to 312 record the name and email address of the Document Shepherd in the 313 tracker -- this will ensure that the Shepherd is copied on necessary 314 email later. 316 In summary, the tasks at the Call for Adoption stage might be as 317 follows: 319 1. Chairs: Select a Responsible Chair to handle the document. 320 2. Responsible Chair: Decide on a work/delegation plan. 321 3. Responsible Chair: Possibly appoint a non-chair Shepherd; else 322 the Responsible Chair becomes the Shepherd. 323 4. Shepherd: Make the call for adoption; set deadlines and schedule. 324 5. Shepherd: Announce the result; Chairs: appoint Document Editor(s) 325 for the WG document. 326 6. Chairs: Update the datatracker; approve -00 version submission. 328 3.2. Stage: Working Group Document 330 Once a -00 version is posted, the Shepherd's primary task is to keep 331 the document moving forward: keeping discussion going, making sure 332 issues are tracked and document updates are posted, and helping 333 things toward consensus. Let's not downplay the importance of active 334 management here: this is where things so often fall short, what 335 causes documents to take *years* to complete. The Shepherd should 336 not rush discussions that are useful, but the Shepherd should make 337 sure that things don't get lost in the forest either. 339 The Chairs will decide how the working group should be managed, and 340 any non-chair Shepherd should be working with the Chairs at this 341 stage, communicating any difficulties and getting help with issue 342 resolution when needed. Tools such as the issue tracker and the 343 working group wiki, which are available to every working group, may 344 be helpful here -- particularly if many issues come up, if issues are 345 often taking a long time to be resolved, or if the same issues tend 346 to come up repeatedly. The issue tracker can be used to record not 347 just the issues themselves, but significant parts of the discussion 348 on both sides, helping to make it clearer what the resolution was and 349 why, and whether a particular request to re-open a closed issue 350 really involves new points or is just a re-hash. 352 Discussions need to be steered, with a goal of avoiding unproductive, 353 circular discussions, re-hashing of old arguments, and tangential 354 discussions that go "off into the weeds". Discussions also often 355 need to be prodded. Lulls can be fine, but when it looks like 356 nothing is happening for a while, remind the participants of open 357 issues, ask for reviews of updated document versions or of recent 358 changes that don't seem to have been discussed. It's often useful to 359 make specific requests of participants off list. The goal here is to 360 ensure that rough consensus is reached on the document, covering as 361 much of the document as possible, and certainly covering the key 362 points. 364 Document Editors need to be prodded as well. We're all volunteers, 365 and many of us are working on a lot of things. A particular document 366 can fall off to the side for a long while. It's best to avoid the 367 trap of getting updates only before each IETF meeting, just in time 368 to beat the submission cutoff. If updates aren't posted fairly 369 promptly after a set of issues is resolved, ask the Editors when 370 they'll be able to get changes rolled into a new document version. 371 Check that the Editors are following working group consensus as they 372 make their updates. 374 Even with plenty of prodding and reminding and steering, it happens 375 that a document simply can't be finished and abandoning it needs to 376 be considered. Perhaps there's no longer the interest there was at 377 adoption. Perhaps the document has been overtaken by other events. 378 Or perhaps there's too much controversy over it, and rough consensus 379 just isn't going to happen. The Shepherd should consult with the 380 Chairs to decide whether the working group should stop work on the 381 document. 383 The Shepherd will know when the document is moving from this stage 384 into the next, and when she needs to shift the focus into preparation 385 for last call and for getting the document to the AD. 387 In summary, the tasks for the Shepherd at the Working Group Document 388 stage might be as follows: 390 1. Work with the Chairs to understand the desired mechanism for 391 managing discussions. 392 2. Watch the discussions as they unfold; call out and record 393 specific issues that come up. 394 3. Steer the discussion when necessary. 395 4. Prod the discussions when necessary. 396 5. Prod the Document Editors when necessary. 397 6. Use appropriate tools, such as issue trackers and wikis. 398 7. Determine when it's time to start wrapping things up and moving 399 to Working Group Last Call. 400 8. Alternatively, determine that it's not possible to move the 401 document forward, and the Chairs need to consider abandoning it. 403 3.3. Stage: Working Group Last Call 405 When any contentious issues have been resolved and the document has 406 had a good level of review, the Shepherd should start looking at when 407 it's time to wrap things up, have a last call within the working 408 group, and get the document ready to send to the Responsible AD. 409 What needs to be done now is largely the same as in the Working Group 410 Document stage, but with a particular aim of getting remaining issues 411 closed and making sure that discussions are tightly focused. Where 412 veering off to explore things that might be added to the document was 413 a fine thing to do in the earlier stages, this is the time to say 414 that the document is "feature complete", and to keep discussions 415 reined in. 417 Working Group Last Call is a recommended step, though not a required 418 one, and most working groups do issue a formal "last call" before 419 sending the document to the Responsible AD. The Shepherd can take 420 the responsibility of issuing that message and of analyzing comments 421 to determine whether things are ready to go ahead. 423 This is also the time to make sure that important reviews are done. 424 Ask for reviews from key working group contributors, and check 425 whether any external reviews are needed. External reviews might 426 include expert reviews for IANA registrations, reviews of formal 427 specifications such as MIBs, XML, and ABNF, and reviews from experts 428 in other areas (does the document need to be checked by a web 429 services expert, a security expert, a DNS expert?). Some of this 430 will happen automatically later -- there will be a Security 431 Directorate review at some point, for example -- but it's easier on 432 the Document Editors and the working group if you know something is 433 particularly necessary and arrange for it sooner. The IANA folks are 434 willing to do an early review of the IANA actions at this stage, so 435 consider asking for that if the document has a large or unusually 436 involved set of IANA actions. 438 The shepherd writeup, which can be found in the IESG section of the 439 IETF web site [Writeup], is a good reference to the Shepherd for 440 making sure the necessary bits are being covered, so this is also a 441 good time to start the writeup. It will be finished later, when the 442 document is ready to be sent to the Responsible AD, but getting a 443 start now can be helpful, and will serve as a reminder to ask the 444 questions and request the reviews that will later be needed. 446 The tasks for the Shepherd at the Working Group Last Call stage might 447 be as follows: 449 1. Issue an official "Working Group Last Call" message on the list, 450 with a reasonable deadline given. 451 2. Closely watch the reviews and discussions at this stage, and make 452 sure they are focused on closing final issues and giving the 453 document final review. 454 3. Specifically ask (perhaps off list) for key reviews. 455 4. Begin preparing the shepherd writeup, and request any external 456 reviews that will be needed. 457 5. Analyze the results of Working Group Last Call and get final 458 updates from the Document Editors. 460 3.4. Stage: Shepherd Writeup Underway 462 Working Group Last Call is over, and the Shepherd has determined that 463 any issues that came out of that have been adequately resolved. It's 464 time to finish up the shepherd writeup, dotting the last of the "i"s 465 and crossing the final "t"s. 467 Remember that the shepherd writeup serves two major purposes: 468 1. It ensures that some key items have been double checked. 469 2. It provides information to the IESG, which is useful during IESG 470 Evaluation. 471 For the first purpose, "yes" and "no" are reasonable answers to some 472 of the writeup questions. In particular, a number of the questions 473 ask if something has been checked, or it some abnormal situation 474 exists. "Yes" to confirm that the check has been made, or "no" to 475 state that the abnormal situation does not exist are fine responses. 476 Of course, if the answer to the first is "no" or to the second is 477 "yes", further explanation is necessary. In other words, "yes" could 478 be a reasonable answer by itself, but "no" would require more by way 479 of explanation... or vice versa. 481 But for the second purpose, providing useful information to the IESG, 482 yes/no responses are of little or no use. Questions about the 483 working group process and discussions are especially looking for some 484 sort of narrative information. Don't just say that there was much 485 discussion that eventually reached consensus, or that there were a 486 number of controversial points that were resolved -- say something 487 about the discussion, talk a bit about the controversies. If there 488 were particular points that simply did not get any discussion but 489 probably should have, say that. 491 Knowing the trouble spots, and the strong and weak points of the 492 discussion and consensus, will allow the IESG to properly evaluate 493 the document. That can avoid the IESG's revisiting issues that were 494 already done to death in the working group. It's common to have 495 DISCUSS positions in which ADs are questioning a point that the 496 working group discussed at length, and a brief explanation in the 497 writeup could have avoided having it come up again then. 499 When the Shepherd has the writeup done, a non-chair Shepherd should 500 consult with the Chairs to make sure they're happy with it and agree 501 with what's in it. The Chairs will then need to make some 502 datatracker updates that only they have authorization for: they will 503 upload the writeup to the tracker and change the document state. 505 Finally, the Shepherd (or the Responsible Chair) will email the 506 writeup to the Responsible AD, with CC to the IESG Secretary, asking 507 that the document be considered for publication. Including the 508 writeup in email, as well as in the tracker, and including the IESG 509 Secretary on CC, are both meant to ensure that nothing gets lost and 510 that a record is kept of the publication request. And as RFC 4858 511 says, the Shepherd should also email the writeup to the working 512 group's mailing list, so the working group is aware of it. The 513 writeup will be public anyway, because it will be in the datatracker, 514 so it can only help the open process to make it more visible to the 515 working group whose work it reflects. 517 See also Section 3.1 of [RFC4858], but note that the writeup template 518 has changed significantly since the version in that document. The 519 current writeup is in the IESG section of the IETF web site 520 [Writeup]. 522 The tasks at the Shepherd Writeup Underway stage might be as follows: 524 1. Shepherd: Complete the shepherd writeup and send it to the Chairs 525 for approval. 526 2. Chairs: Work with the Shepherd to finalize the writeup. 527 3. Chairs: Put the writeup into the datatracker, and change the 528 tracker document state to the appropriate one for requesting 529 publication. 530 4. Shepherd: Send the writeup to the Responsible AD (and the IESG 531 Secretary) and request publication. 533 3.5. Stage: AD Review 535 The next stage in the process is up to the Responsible Area Director, 536 and the Document Shepherd has but one easy task: make this stage as 537 short as possible. The Responsible AD or the IESG Secretary will do 538 some document state changes in the datatracker (to Publication 539 Requested and then to AD Review), and the AD will review the document 540 and either request IETF Last Call or respond to the authors (and, we 541 hope, to the Shepherd as well; here's where it was useful to have put 542 the Shepherd's email address in the tracker) with review comments and 543 suggested changes. In the latter case, the document's state will 544 change to "AD Review, Revised I-D Needed". 546 The Shepherd needs to watch for the key state changes and the AD's 547 review. If the review doesn't happen in a reasonable time -- 548 allowing for a busy AD's schedule and remembering that the document 549 you're shepherding isn't the only one on the AD's docket -- send a 550 reminder... perhaps as a question, "How is the review on 551 draft-ietf-frobozz-xyzzy coming?" Use your judgment to decide how 552 long to wait, but most ADs will appreciate a reminder here and there 553 as long as it's not at the level of "pestering". 555 Once the review comes in, make sure the Document Editors are on top 556 of it and respond in a timely manner. Make sure that the working 557 group is consulted on issues brought up in the review that are 558 significant enough to require the working group's engagement in the 559 response. Editorial tweaks can arguably be handled by the editors 560 alone at this point, and changes to the protocol clearly need to go 561 back to the working group, but many issues fall in between, and good 562 judgment is important. 564 Many documents spend *months* in AD Review state, largely because of 565 lack of good shepherding. It may look like there's only one major 566 task here, but it's an important one. Please don't give it short 567 shrift. 569 See also Section 3.2 of [RFC4858]. 571 The tasks for the Shepherd at the AD Review stage might be as 572 follows: 574 1. Make sure the AD reviews the document in a timely manner, and 575 send occasional reminders as needed. 576 2. Make sure the Document Editors respond to the review in a timely 577 manner, and poke them as well, as needed. 578 3. Keep the dialogue going between the Responsible AD and the 579 editors until all issues have been dealt with and the document is 580 ready for the next stage. 582 4. See to it that issues are brought back before the working group 583 if they are significant enough to require it. 585 3.6. Stage: IETF Last Call 587 Once the Responsible AD is satisfied that the document is ready to 588 move ahead, she will put it in Last Call Requested state. That 589 prompts the IESG Secretary to send out the Last Call announcement and 590 to put the document into "In Last Call". 592 The Shepherd's job in the IETF Last Call stage is very similar to 593 what's needed in AD Review. Start by watching for last-call 594 comments, including various special reviews. Reviews will come in 595 from the Security Directorate and the General Area Review Team 596 (GenART), and some may also come from other review teams and 597 directorates. Reviews might also be coming in at this stage, if they 598 haven't already, that were specifically requested by the Shepherd 599 (see the Working Group Last Call stage). 601 The Shepherd needs to make sure all of those reviews are addressed by 602 the document editors, and that the specifically requested reviews get 603 done. "Addressed" doesn't mean that every change asked for in every 604 last-call comment needs to be made. Sometimes, a reasonable response 605 is to say that the working group discussed the point, and the 606 document correctly reflects its consensus -- that is, the working 607 group disagrees with the last-call comment. At other times, it's 608 reasonable to disagree with the reviewer and look for any other 609 support for the reviewer's position. Rough consensus can be a tricky 610 thing, but the bottom line is that all comments need at least be 611 considered. Directorate and review-team reviews, in particular, 612 require acknowledgment and response (though they, too, can be 613 disagreed with). 615 During Last Call, IANA will review the document's IANA 616 Considerations, will respond with their summary of what they think 617 needs to be done by IANA after the document is approved, and will ask 618 any questions they have. The Shepherd should watch for this review 619 and make sure that the actions IANA proposes are correct and that any 620 questions they have are answered. See also Section 4 of [RFC4858]. 622 Different Responsible ADs will have different preferences for whether 623 documents in IETF Last Call should be updated while they're still in 624 that state. The Shepherd should check with the AD and advise the 625 Document Editors. Sometimes it's best to keep a stable version 626 throughout last-call review; other times it's better to get changes 627 posted quickly, so the same issues aren't brought up by multiple 628 reviewers. Work with the AD and the editors to handle this. 630 The tasks for the Shepherd at the IETF Last Call stage might be as 631 follows: 633 1. Monitor the last-call comments, and make sure that specifically 634 requested reviews arrive. 635 2. Make sure the Document Editors respond to all reviews and 636 comments in a timely manner. 637 3. Keep the dialogue going between the community and the editors 638 until all issues have been dealt with. 639 4. See to it that issues are brought back before the working group 640 if they are significant enough to require it. 642 3.7. Stage: Waiting for AD Go-Ahead 644 When Last Call completes, the tracker state for the document will 645 automatically go to "Waiting for AD Go-Ahead". This is the 646 Shepherd's signal to re-check the comments from last call, to make 647 sure an updated I-D is posted that is ready for IESG Evaluation, and 648 to let the Responsible AD know when everything is set. The AD will 649 be watching for this as well, and in many cases the Shepherd won't 650 need to be involved here. But, as in the other stages, it's the 651 Shepherd's responsibility to keep an eye on things and make sure 652 what's needed gets done. 654 The tasks for the Shepherd at the Waiting for AD Go-Ahead stage might 655 be as follows: 657 1. Make sure a new I-D is posted with the latest changes, unless 658 there were no changes required. 659 2. Inform the Responsible AD that all changes have been 660 incorporated, and that the document is ready for IESG Evaluation. 661 3. Update the Shepherd writeup if anything has come up during Last 662 Call that the IESG should know about. 664 3.8. Stage: IESG Evaluation 666 As the ADs do their reviews they will record ballot positions on the 667 document. Ballot positions can be one of "Yes", "No Objection", 668 "Discuss", and "Abstain" (there's also "Recuse" for cases when the AD 669 has a conflict of interest with the document (if, for example, the AD 670 is one of the authors/editors)). Any of these ballot positions can 671 be accompanied by non-blocking review comments, and "Discuss" also 672 comes with blocking comments in addition -- these must be resolved to 673 the satisfaction of the Discussing AD before the document can be 674 approved by by the IESG. The document will be scheduled for a bi- 675 weekly "telechat" (at the time of this writing they're on Thursdays), 676 and it will be approved then or left in one of several follow-up 677 states. 679 The IESG Evaluation period is normally somewhere between one and 680 three weeks, though it can be as little as a day or two in unusual 681 circumstances. Be aware, though, that there's usually a burst of 682 review activity in the final few days before the telechat, and expect 683 most reviews to come in then. 685 The IESG Evaluation comments and DISCUSS positions will be copied to 686 the Document Shepherd (again, it was important to have put the 687 Shepherd's email address in the tracker), and the Shepherd should be 688 watching for them and making sure that the Document Editors respond 689 promptly -- at this stage, quick turnaround is most important. 690 Sometimes the Shepherd or Chairs might respond to AD questions and 691 comments themselves, and sometimes they might leave it to the 692 editors. The process works best when everyone engages, with the goal 693 of resolving the issues brought up by the ADs as efficiently as 694 possible. 696 A word about DISCUSS positions: Many Document Editors treat these as 697 adversarial situations created by aggressive ADs, but that's 698 generally not the intent. First, many DISCUSSes are resolved quickly 699 and easily by a round of email with the Discussing AD, and that's as 700 it should be: the point is that the AD has something to "discuss" 701 with those responsible for the document before she can agree to the 702 document's approval. Second, many DISCUSSes that do take more 703 effort, often significant back and forth with the Discussing AD and 704 other IESG members, result in a better document, having cleared up 705 some significant confusion or having closed a hole in the 706 specification that was missed at earlier stages. Please try to treat 707 the situation as one in which everyone is looking to make the 708 document better. 710 Most often, ADs who record DISCUSS positions (and review comments) 711 are quite responsive, and will work with the Editors and Shepherd to 712 get everything resolved. Sometimes, though, a busy AD can find 713 herself lacking the time to respond. The Shepherd should keep the 714 ADs honest, pushing for quick responses. In earlier stages, too- 715 frequent reminders might be considered unreasonable, but at this 716 stage discussion should be fairly brisk, and a delay of more than a 717 couple of days should be unusual, on either side. 719 The IESG web site has more details about IESG ballot positions 720 [Ballot] and about IESG DISCUSS ballots in particular [Discuss]. And 721 see also Section 3.3 of [RFC4858]. 723 The tasks for the Shepherd at the IESG Evaluation stage might be as 724 follows: 726 1. Keep track of the DISCUSS positions and review comments by the 727 IESG. 728 2. Make sure all comments are addressed, and help the discussions of 729 DISCUSS positions reach closure. 730 3. Keep both the Document Editors and the Discussing AD engaged in 731 the resolution of the issues. 733 3.9. Stage: Approved by the IESG 735 Once the document has been on a telechat, any necessary revised 736 versions have been posted, and all DISCUSS positions are "cleared", 737 the Responsible AD (or the IESG Secretary) will put the document into 738 the "Approved, Announcement to be Sent" state. If there's any 739 follow-up that needs to be done, it will be held with a sub-state 740 (usually "Point Raised, Writeup Needed"), and the Shepherd should 741 make sure whatever final checks that are needed get done, and that 742 the Responsible AD clears the sub-state and informs the IESG 743 Secretary. 745 At this stage, it's usually a matter of making sure that the latest 746 version of the document adequately addresses the non-blocking 747 comments by the ADs, and that any necessary RFC Editor notes are 748 entered. The Shepherd should work with the Responsible AD to 749 understand what still needs to be done, and to make sure it happens. 751 The tasks for the Shepherd at the Approved by the IESG stage might be 752 as follows: 754 1. Work with the Responsible AD to understand what still needs to be 755 addressed. 756 2. Double-check the IANA actions and the RFC Editor notes, and 757 follow up on any errors or omissions. 758 3. Make sure the Document Editors and the Responsible AD move the 759 document to the final Approved state. 761 3.10. Stage: In RFC Editor Queue 763 Shortly after the approval announcement is sent out, the document 764 will go into the RFC Editor queue, and the Shepherd will start seeing 765 it pass through a number of RFC Editor states. For most of this, the 766 Shepherd need do nothing, and is just waiting for the AUTH48 state. 767 This will usually take between a few weeks and a few months, 768 depending upon many factors, but it can be held up indefinitely by 769 normative references to documents that are not yet ready for 770 publication. Be aware of what the document is waiting for, and 771 otherwise just wait. If anything looks odd, ask the Responsible AD 772 to check. 774 The tasks for the Shepherd at the In RFC Editor Queue stage might be 775 as follows: 777 1. Sip tea or drink beer or wine, and wait for AUTH48. 778 2. Talk to the Responsible AD if something doesn't look right. 780 3.11. Stage: AUTH48 782 AUTH48 is an RFC Editor state that occurs when the RFC Editors have 783 done their final edits on the document before publication. It's 784 meant to represent a 48-hour period in which the AUTHors can review 785 what the RFC Editor has changed, have a final look at the document, 786 and make sure it's ready to go. 788 AUTH48 is a critical document state; do not downplay its importance. 789 At this stage, the Shepherd should re-review the document, paying 790 special attention to recent changes. The Document Editors must do 791 the same, and a response from every Author/Editor listed at the top 792 of the document is required before the RFC Editor will finish the 793 publication process. The Document Shepherd needs to make sure that 794 the Editors all respond, and should take the lead in prompting them 795 early and frequently. Remember that "AUTH48" is meant to refer to 48 796 hours, not 48 days. Don't let this drag on. 798 The RFC Editor will often have questions that the Authors/Editors 799 need to answer. The Document Editors often have minor changes to 800 insert at this point. The Shepherd should consider those answers, 801 those changes, and the changes the RFC Editor has made leading into 802 AUTH48, and assess (in consultation with the Chairs and the 803 Responsible AD) whether any changes need to be passed back to the 804 working group -- remember that the document has been approved by 805 rough consensus of the working group, and then of the IETF as a 806 whole, and the final, published version must continue to reflect that 807 consensus. 809 It's unusual for there to be significant controversy at this stage, 810 but it's been known to happen. Sometimes a change or a question by 811 the RFC Editor will raise a question with the Document Editors that 812 had not come up before. Sometimes, the right answer to one of those 813 questions will be more than just editorial, and sometimes it will 814 involve a significant technical decision. Decisions of that nature 815 should not be made by the Document Editors alone, and the Shepherd 816 should arrange to have them discussed by the working group. 818 Most of the time, though, this stage will run smoothly, the Document 819 Editors will respond to the AUTH48 messages with a minimum of 820 prodding, and the RFC Editor will announce their happiness and 821 proceed with the publication process. 823 See also Section 5 of [RFC4858]. 825 The tasks for the Shepherd at the AUTH48 stage might be as follows: 827 1. Monitor the AUTH48 process and make sure all questions are 828 answered and all Authors/Editors respond as needed. 829 2. Assess whether any issues that come up are significant enough to 830 need review by the working group. 832 3.12. Stage: Published 834 We're done. The RFC Editor has published the document, and the RFC 835 announcement has been made. Many thanks to the Shepherd for having 836 seen it through and for helping to assure a high quality document. 838 4. Some Final Notes 840 I've outlined a Document Shepherding Function, above, in a lot of 841 detail, so let's put the executive summary back here: 843 What it all boils down to is setting up one person who takes 844 responsibility for following the progress of a document from Call for 845 Adoption through Publication, staying actively involved with managing 846 the discussion and issue resolution at every stage, and making sure 847 the necessary participants are responsive and that things don't 848 languish from inattention. 850 And again, Working Group Chairs may delegate all or part of this 851 function to a non-chair participant, or retain all responsibility for 852 it themselves. In the latter case, I don't think what I'm describing 853 here is anything different to what should be happening already. 854 Setting it out as clear tasks and a set of stages in the document's 855 lifecycle will make it easier to recognize what needs to be done 856 when, and to handle delegation when the Chairs choose to delegate. 858 5. Security Considerations 860 This document describes an individual's suggestion about IETF 861 process, and is entirely unrelated to security in any way. 863 6. IANA Considerations 865 No IANA actions are requested by this document, and the RFC Editor is 866 asked to remove this section before publication. 868 7. References 870 7.1. Normative References 872 [RFC2418] Bradner, S., "IETF Working Group Guidelines and 873 Procedures", BCP 25, RFC 2418, September 1998. 875 [RFC4858] Levkowetz, H., Meyer, D., Eggert, L., and A. Mankin, 876 "Document Shepherding from Working Group Last Call to 877 Publication", RFC 4858, May 2007. 879 7.2. Informative References 881 [Ballot] IESG, "IESG Ballot Procedures", May 2009, 882 . 884 [Discuss] IESG, "DISCUSS Criteria in IESG Review", July 2007, 885 . 888 [Stmt] IESG, "IESG Statement on Document Shepherds", 889 October 2010, . 892 [Writeup] IESG, "Working Group Submission Writeup", February 2012, 893 . 895 Author's Address 897 Barry Leiba 898 Huawei Technologies 900 Phone: +1 646 827 0648 901 Email: barryleiba@computer.org 902 URI: http://internetmessagingtechnology.org/