Network Working Group A. Mankin Internet-Draft Shinkuro, Inc. Expires: April 3, 2006 T. BD TBD September 30, 2005 Requirements for IETF Technical Publication Service draft-mankin-pub-req-00 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on April 3, 2006. Copyright Notice Copyright (C) The Internet Society (2005). Abstract The work of the IETF is to discuss, develop and disseminate technical specifiations to support the Internet's operation. As the the IETF progresses, document and review of its requirements for the process and structure of its technical specification publication is increasingly important, in order to ensure continued support for the IETF's work. Mankin & BD Expires April 3, 2006 [Page 1] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Stages in the Technical Specification Publication Lifetime . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Requirements Discussion . . . . . . . . . . . . . . . . . . . 5 4. Requirements for IETF Technical Specifications Publication Process . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.1. Beginning-to-end Status Tracking . . . . . . . . . . . . . 6 4.2. Post-approval timeframes . . . . . . . . . . . . . . . . . 6 4.3. Fast Tracking . . . . . . . . . . . . . . . . . . . . . . 7 4.4. Non-Author Editing . . . . . . . . . . . . . . . . . . . . 7 4.5. Post-Approval, Pre-Publication Changes . . . . . . . . . . 8 4.6. Post-Publication Changes: Maintaining and Updating Errata . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.7. Indexing: Publisher Maintenance of the Catalog . . . . . . 9 4.8. Mechanisms for Changes to Tech Spec Style . . . . . . . . 9 5. Two Experiments . . . . . . . . . . . . . . . . . . . . . . . 10 5.1. Early Copy Editing of WG Documents by the RFC Editor . . . 10 5.2. Stable Permanent Identifier at Approval . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 Intellectual Property and Copyright Statements . . . . . . . . . . 17 Mankin & BD Expires April 3, 2006 [Page 2] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 1. Introduction The work of the IETF is to discuss, develop and disseminate technical specifications to support the Internet's operation. An important output of the IETF, then, is published technical specifications. As the IETF progresses, documentation and review of its requirements for the process and structure of technical specification publication is increasingly important, in order to ensure continued support for the IETF's work. The term "technical specification" is used here purposefully to refer to the technical output of the IETF. This document does not engage in the debate about whether it is expressed as RFCs or ISDs, what "is" an RFCs, how to classify, etc. All of that is out of scope. The intention of this document is to clarify the IETF's consensus on its requirements for its technical publication service. Discussing these requirements in relation to the existing service carried out by the RFC Editor is not a goal of this document. However, short and mid-term experiments with newly understood requirements might be conducted by the IETF and RFC Editor, so a section below does open some discussion on this topic. Mankin & BD Expires April 3, 2006 [Page 3] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 2. Scope The scope of this document is very specifically on the requirements of the publication process for technical specifications, leaving aside many of the other important topics related to the contribution to and creation of Internet-Drafts. Examples of topics that are important, but are consciously not addressed here, are: o what will be in the acknowledgements section -- while the publisher of a specification may want some input on this, this is of a low priority for the discussion here. o the meta-topic of document formats -- it is imperative to get a firm agreement of the entire technical specification publication process before zeroing in on formats for any part of it. Nevertheless, it is important that the requirements laid out here do not place undue restrictions on future document format possibilities. 2.1. Stages in the Technical Specification Publication Lifetime Figure 1 below provides a useful summary of where technical publication falls in the current lifetime of a document in the IETF. This figure shows a working group document and the review includes an IETF Last Call (LC). The lifetime is very similar for AD-sponsored IETF documents, such as documents which update IETF protocols where there is no longer a working group, or process update documents. | Author | WGLC | IESG, | | Tech Actors | or | AD | Shepherd, | A | Publisher, | Editor | IETF LC | Editor, | P | input from | | IANA | WG | P | authors, et al | | IESG | | R | Actions | Creation | | Resolution | O | non-author | and | Formal | of all | V | editing, | Editing | Reviewing | reviews | A | other | | | | L | publication |_________________| |______________________| |_________________| In WG Out of WG - Post-Approval Pre-Approval Figure 1: Stages of a Working Group Document Mankin & BD Expires April 3, 2006 [Page 4] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 3. Requirements Discussion The rest of this memo discusses a series of requirements or postulated requirements for the IETF on the post-approval technical publication of its documents. In two case, the memo has a later section describing an experiment for directed change from the 2005 situation, but otherwise, as stated, the requirements are presented in the abstract. The topics are o Beginning-to-end status tracking - more view into publication o Post-approval timeframes o Fast tracking o Non-author editing (publisher editing) o Post-approval, pre-publication changes (by the IETF) o Errata o Beyond errata The list goes on for a few more, but this small list here illustrates the idea. The IETF should determine what services best support its technical documents, and what the best tradeoffs are, then when the IAB, Internet Adminstrative Director and the Internet Adminstration Oversight Committee work on the Technical Publication function for the IETF, they have a clear picture of the IETF's expressed requirements. (And also, during any particular implementation of the technical publication goals, the IETF can use these clearly expressed goals as a baseline). Mankin & BD Expires April 3, 2006 [Page 5] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 4. Requirements for IETF Technical Specifications Publication Process This section lists the set of requirements for IETF technical specifications publication. In each case, the current status is described (in terms of the extent to which the requirement is met and/or the means in which it is handled). Illustrations are provided. 4.1. Beginning-to-end Status Tracking In order to function as a full publication process, enabling all participants to fully contribute to, review, revise and reference specifications, it is imperative that all members of the IETF community have current and accurate information about the status of a specification publication. This may mean the need for a unified tracking system for technical publication, from the creation through the publication, or it may mean full detailing of status during the publication (access to more status during queuing time). Current status? I.e., what is/is not tracked today. 4.2. Post-approval timeframes The IETF does not work in a vacuum. Many organizations (SDOs and implementing entities) depend on the IETF's specifications. Therefore, the IETF needs to be able to provide permanent references for, and final text of, specifications within a fixed time from the IETF's approval. Currently, the IETF has stated that it requires a stable permanent reference within a month of approval of the document, and that the final text must be available within 2 months. In special circumstances, there may be a requirement to expedite that process. A consideration for the stable permanent reference is whether it should also be held out till the 2 month point. RFC 2026 stipulates that a document approval may be appealed up till 2 months after its approval. Note that this requirement is heavily interdependent with other requirements. It has implications for authors, editors, and protocol parameter assignment personnel: they must be committed to timely action for their followup on any final reviews, changes, and actions needed post-approval. (Small delays add up shockingly if one is looking for a month or two month turn-around; the AD and working group shepherd really has to act as a herder on this). The purpose of this section is not to discuss the current post- Mankin & BD Expires April 3, 2006 [Page 6] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 approval time-frame, though in the Experiments below, we provide a suggestion for decoupling the provision of the stable permanent reference from the technical publishers editing queue present and future. The purpose here is to understand whether the IETF agrees that we have these requirements, as well as accepting the requirement on ourselves of timely actions, if we support these requirements. o Stable permanent reference one or two months after approval o Published document at a predictable time after approval 4.3. Fast Tracking The technical publication service has a publication priority. In the ideal case, the the IETF would produce documents less quickly than the publication service could publish them, but this cannot be guaranteed for all future circumstances, and is not the case at the present writing, so there is a (substantial) queue with categories of priority (IETF working group standards track have high priority currently, e.g.). Under special circumstances, with documentation, the IESG vote to ask the IETF Secretariat to send a message requesting expediting publication for a newly approved document. These circumstances are usually the requirement that the approved document have a stable permanent reference for another standards body's shortly to be published standard. Our experience is that lacking the stable reference, other bodies often simply incorporate the text of the last snapshot internet-draft in an appendix to their document, which is highly undesirable. But whether or not the pressure is as great as that, the expediting of the stable reference, called fast-tracking, is often a requirement. To what extent does the IETF require that the publication accompany the permanent stable reference in these cases, if the requestor only requires the reference? 4.4. Non-Author Editing In the post-approval period, the technical publisher performs an editing role. This use of the word "edit" is very different from "editing" in the pre-approval period. The WG's Editor manages language and consensus from the IETF working group, Last Call and review process. The technical publisher's non-author editor, in that editing process, is interested not in any aspects of the IETF development, but only in improving readability, correcting spelling and grammar errors, and so on. These are laudable goals in any piece of writing, and the IETF should always be attempting to give less Mankin & BD Expires April 3, 2006 [Page 7] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 onerous work to a technical publisher in this area by writing correctly and not "leaving that writing error to be caught later". But there are tradeoffs in the degree of non-author editing that is done, and the IETF needs to discuss the requirements it wants for this. How much copy editing is enough? corrections to errors only? or rewriting of the sentences to the dictates of a style manual, so that passives are rewritten, clauses moved and so on. All the authors are then requested to check the changes and confirm whether they are acceptable. If the changes are extensive (and in the past year, styles changes have amounted to 40-100 substantial changes in some documents) these checks can take quite a bit of time. The technical publisher's editor is unaware of WG consensus text wordings. If those are very poorly written, then some intervention is valid, but if the changes are for stylistic reasons, and they affect a careful agreement, the working group may need to rework the change. What is required here? What are the benefits versus the cost to the IETF working groups of the copy edits in these cases? What do IETF participants want? The technical publication's editor is not always well aware of technical information and may modify technical meanings in making a stylistic alteration of some ambition. What is required here? What are the benefits versus costs to IETF working groups overall? What do IETF participants want? It has been suggested that the best thing is to collect data and to involve the working groups ore heavily in the copy editing of the documents, to deal with both of the above questions. The two issues above both result in long timeframes for author approval of changes (and author requests to not make a number of the technical editor copy edits). An experiment on Early Copy Edits is discussed below. 4.5. Post-Approval, Pre-Publication Changes Though occurring at the same time as the technical publisher's copy edits, the post-approval, pre-publicaton changes referred to in this section come from the IETF, and raise problems for us because they are often extensive and time-consuming. The document becomes ready for publication, the copy edit comes to the authors and editors, and the primary author or perhaps several of them, present the publisher, with a long list of their own changes. These fall into a number of categories, and it may be suggested that the IETF could agree that some of these are procedurally permitted (with appropriate steps) and some not: Mankin & BD Expires April 3, 2006 [Page 8] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 o Changes the author or editor wants because document will read better o Technical change WG has found and agreed on since approval o Small update needed to match another spec approved since approval o Serious technical bug found since approval The IETF has held that the author and editor are not the 'owners' of the document so that the first type is not a valid request. That should not be a requirement. The IETF might decide to accept the other types, but perhaps require them to be submitted only within a fixed time after approval, rather than having them submitted in the last few days before publication, when they contribute to delay. The last type, the serious bug, would need to be reportable up to the last moment. 4.6. Post-Publication Changes: Maintaining and Updating Errata A technical publications service maintains errata for the publications. If a bug or error is found after the document is issued, rather than republishing a corrected copy, because of the stickiness of web copies, a specific error notice is placed on a web page. What does the IETF require for this service in terms of: o Public awareness o Review of the erratum (who, transparency) o Timeliness of posting o Is this the right service? 4.7. Indexing: Publisher Maintenance of the Catalog To come 4.8. Mechanisms for Changes to Tech Spec Style To come Mankin & BD Expires April 3, 2006 [Page 9] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 5. Two Experiments The following are presented as experiments against the existing IETF. One is running currently. The second might or might be proposed, but it is listed as an experiment because it is given a fairly concrete form. 5.1. Early Copy Editing of WG Documents by the RFC Editor Time: September 20005 - November 2005 Objectives: Improve document quality early on Experiment to perform as much of the editorial work as possible early in the process, e.g., before working group last call. This note describes a very limited initial experiment that should begin to sort out the issues. We can then decide whether further experimentation is warranted. Expected impact: o positive impact on WG Last Call, AD review, IETF Last Call and IESG review. This is expected because of clearer/better text early on. o less copy-editing, so faster process after IESG approval. This hopefully reduces the time between IESG approval and RFC publication. o Reduction of time spend in status AUTH48. This is expected because there should be less changes (if any) between the approved text and the rfc-to-be-published. This seems to insert post-approval activity into the pre-approval period. But in fact it makes what was a serial process a partly parallel one. Part of the study is to determine if this parallelizing holds good, and there is not a long interlude on copy editing at the end of the publication period for these experiment documents. 5.2. Stable Permanent Identifier at Approval A large fraction of IETF documents have either SDOs or implementor consumers who require a stable permanent identifier as soon as the document is approved. This is a compliment to the value of the IETF's work. Although simply providing the technical publications right away seems desirable, there are operations research arguments Mankin & BD Expires April 3, 2006 [Page 10] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 to suggest that the IETF offer what the IETF can control, the output of the IETF's approval, not gated on a service we can only give requirements for. Here is an outline for steps in an experiment for the IETF providing the stable permanent identifier at approval, and how this would modify the requirements for the technical publication: o IESG approves document, which may include some text changes in the form of Notes to the Publisher o IANA performs IANA actions for the document as usual and places usual i-d placeholder o The two month timeout on appeals runs out (document approval is now final). o IESG assigns stable permanent identifer to the document and passes this to IANA and Technical Publisher o IANA can now update registry with the stable permanent identifier o At this time the editor must prepare a new internet draft with filename to be determined but which includes the stable permanent identifier o The internal headers must be modified so that they include the stable permanent identifier and convey the approval status and non-expiration of the document, for instance: OLD: INTERNET-DRAFT September 5, 2005 Expires: March 5, 2006 NEW: RFC-TO-BE #### Approved September 30, 2005 Expires at RFC Publication The new draft would not be as polished as the RFC publication, but it would incorporate the text changes and would be technically stable. Related to the section above on post-approval changes, if the timeframe for those is set as a requirement at two months, this draft can shepherded to include those and exclude all future, other than severe bugs that were discovered. The shepherds for the document should encourage that normative Mankin & BD Expires April 3, 2006 [Page 11] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 references for the document have stable permanent references already, for the citations. This experiment would raise many questions: transition, execution, but it pulls together a number of the requirement threads. Mankin & BD Expires April 3, 2006 [Page 12] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 6. IANA Considerations Any requirements that result from this discussion need to be reviewed by IANA and the IETF to understand to what extent, if any, the work flow of the documents through IANA are affected. Mankin & BD Expires April 3, 2006 [Page 13] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 7. Security Considerations There is a tussle between the sought-for improvements in readability and the specific language that has often been negotiated carefully for the security content of IETF documents. In general, it seems that clarifying the technical publication requirements seems likely to make sure that the IETF's secure protocols get out more effectively and with better result. Mankin & BD Expires April 3, 2006 [Page 14] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 8. Acknowledgements The early copy edit experiment writeup is by Bert Wijnen. Leslie Daigle has contributed strongly to this text throughout. 9. References [1] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", RFC 2434, BCP 26, October 1998. [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, BCP 14, March 1997. Mankin & BD Expires April 3, 2006 [Page 15] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 Authors' Addresses Allison Mankin Shinkuro, Inc. 1025 Vermont Avenue Washington, DC 20005 USA Phone: +1 301 728 7199 Email: mankin@psg.com, mankin@shinkuro.com URI: http://www.psg.com/~mankin/ TBD TBD Phone: Email: tbd.com URI: Mankin & BD Expires April 3, 2006 [Page 16] Internet-Draft draft-mankin-techspec-pubreq-00 September 2005 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2005). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Mankin & BD Expires April 3, 2006 [Page 17]