From: http://www.ietf.org/internet-drafts/draft-mankin-pub-req-08.txt Title: Requirements for IETF Technical Publication Service Reference: IETF Working Group, Internet-Draft 'draft-mankin-pub-req-08.txt' Date: May 8, 2006 See also: http://xml.coverpages.org/specProduction.html#mankinPubReq08 ======================================================================== Network Working Group A. Mankin Internet Draft Expires: November 2006 S. Hayes Ericsson May 8, 2006 Requirements for IETF Technical Publication Service draft-mankin-pub-req-08.txt 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 November 8, 2006. Abstract The work of the IETF is to discuss, develop, and disseminate technical specifications to support the Internet's operation. Technical publication is the process by which that output is disseminated to the community at large. As such, it is important to understand the requirements on the publication process. Mankin & Hayes Expires November 8, 2006 [Page 1] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 Table of Contents 1. Introduction...................................................2 2. Scope..........................................................3 2.1. Stages in the Technical Specification Publication Lifetime4 3. Technical Publication Tasks and Requirements...................5 3.1. Pre-approval review or editing............................6 3.2. Preliminary Specification Availability....................6 3.3. Post-Approval Editorial Cleanup (non-Author Editing)......7 3.4. Validation of references..................................9 3.5. Validation of formal languages............................9 3.6. Insertion of Parameter Values............................10 3.7. Post Approval, Pre-Publication Technical Corrections.....10 3.8. Allocation of Permanent Stable Identifiers...............11 3.9. Document Format Conversions..............................11 3.10. Language Translation....................................12 3.11. Publication Status Tracking.............................12 3.12. Expedited Handling......................................13 3.13. Exception Handling......................................13 3.14. Notification of publication.............................14 3.15. Post Publication Corrections............................14 3.16. Indexing: maintenance of the catalog....................15 3.17. Access to Published Documents...........................15 3.18. Maintenance of a Vocabulary Document....................16 3.19. Providing Publication Statistics and Status Reports.....16 3.20. Process and Document Evolution..........................17 3.21. Tutorial and Help Services..............................17 4. Technical Publisher Performance Metrics.......................18 4.1. Post-approval timeframes.................................18 4.2. Publication Throughput...................................19 4.3. Non author changes Generated during Publication..........19 4.4. Author changes generated during publication..............20 5. IETF Implications of Technical Publication Requirements.......20 6. IANA Considerations...........................................21 7. Security Considerations.......................................21 8. Acknowledgments...............................................22 Author's Addresses...............................................22 Intellectual Property Statement..................................22 Disclaimer of Validity...........................................23 Copyright Statement..............................................23 Acknowledgment...................................................23 1. Introduction The work of the IETF is to discuss, develop, and disseminate technical specifications to support the Internet's operation. An Mankin & Hayes Expires November 8, 2006 [Page 2] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 important output of the IETF, then, is published technical specifications. The IETF technical publisher is responsible for the final steps in the production of the published technical specifications. This document sets forth requirements on the duties of the IETF technical publisher and how it interacts with the IETF in the production of those publications. 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 RFC, how to classify them, etc. These issues are considered out of scope. The intention of this document is to clarify the IETF's consensus on its requirements for its technical publication service. This document is not a discussion of how well the RFC Editor fulfils those requirements. 2. Scope The scope of this document is the requirements for the technical publication process for IETF. Requirements on a technical publisher can be expressed in terms of both what tasks the IETF technical publisher is responsible for and performance targets the IETF technical publisher should meet. This draft only addresses those documents published by the IETF family. These include IETF documents processed by the IESG, IAB documents, and IRTF documents processed by the IRSG. It specifically excludes independent submissions that go directly to the Technical Publisher. The handling of independent submissions may well be a requirement on the technical publisher, but it is not one associated with the IETF publication process and hence is outside the scope of this document The list of potential technical publication tasks was derived by considering the tasks currently performed by the RFC editor as well as the responsibilities of the technical publishers in other standards organizations including 3GPP, ATIS, ETSI, IEEE, and ITU. This requirements documents focuses on process issues in how the IETF technical editor serves the IETF. There are related issues regarding non-technical aspects of document content that are not addressed in this requirements document. Issues not addressed in this document are: Mankin & Hayes Expires November 8, 2006 [Page 3] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 o Policies governing the acceptable input and output document formats (including figures, etc.), o Policies governing the acceptable character sets (internationalization) o Policies governing the layout and style of published documents o Policies governing the contents of non-technical sections (acknowledgement sections, reference classifications, etc.) It is realized that the above policies are also an important aspect in determining the final published product from IETF. These policies are likely to evolve as part of the ongoing IETF dialog. The IETF technical publisher must be part of the discussions of these policies and be prepared to implement and facilitate policy changes as they are determined by IETF consensus. This requirement is captured under the discussion of process and document evolution. 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 that update IETF protocols where there is no longer a working group, or documents on interdisciplinary topics. | Author | WGLC | IESG, | | IANA, Actors | or | AD | Shepherd, | A | Tech | Editor | IETF LC | Editor, | P | Publisher, | | IANA | WG | P | input from | | IESG | | R | authors, et al | | | | O | Actions | Creation | | Resolution | V | non-author | and | Formal | of all | A | editing, | Editing | Reviewing | reviews | L | other | | | | | publication |---------------| |---------------------| |----------------| In WG Out of WG Post-Approval Figure 1: Stages of a Working Group Document Mankin & Hayes Expires November 8, 2006 [Page 4] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 Note that in some cases a single submission may actually consist of multiple source documents (supporting files, code, etc.). 3. Technical Publication Tasks and Requirements Standards development organizations all have technical publication as part of their process. However, the boundaries between what is done by the technical committees and the technical publisher vary. The following are potential tasks of a technical publisher. The following list was derived after analyzing the technical publication policies of the IETF and other standards development organizations. For each of these tasks we discuss its relevance to IETF and how it is realized within the IETF processes. Based upon this information we derive requirements on the IETF technical editor: 1. Pre-approval review or editing 2. Preliminary specification availability 3. Post-approval editorial cleanup 4. Validation of references 5. Validation of formal languages 6. Insertion of parameter values 7. Post approval, pre-publication corrections 8. Allocation of permanent stable identifiers 9. Document format conversions 10.Language translation 11.Publication status tracking 12.Expedited handling 13.Exception handling 14.Notification of publication 15.Post-publication corrections (errata) 16.Indexing: maintenance of the catalog Mankin & Hayes Expires November 8, 2006 [Page 5] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 17.Access to published documents 18.Maintenance of a vocabulary document 19.Providing publication statistics and status reports 20.Process and document evolution 21.Tutorial and help services 3.1. Pre-approval review or editing Task Description: In many cases the technical publisher may provide a review or editing service to improve document quality prior to the approval of a document. This review process would normally address issues such as grammar, spelling, formatting, adherence to pre- approval boilerplate, document structure, proper use of keywords (RFC 2119), etc. The primary advantage of pre-approval review is that review of the changes is handled as part of the regular review and approval process. Discussion: Pre-approval review is not part of the normal process flow with the IETF but this concept has been explored in the early copy editing experiment. Early feedback from the experiment has been promising, however, the effectiveness of early copy-editing is still being evaluated. Derived Requirements: o Req-PREEDIT-1: The IETF technical publisher should perform an editorial review of documents before WG last call and provide feedback to the authors to improve quality of the documents. This review should strive to maintain consistency in appearance with previously published documents. 3.2. Preliminary Specification Availability Task Description: Some standards organizations require their publisher to make available a preliminary version of a document (with appropriate caveats) to make the information available to the industry as early as possible. This document is provided "as is" after the approval. This document is withdrawn once the final document is published. Mankin & Hayes Expires November 8, 2006 [Page 6] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 Discussion: This is not required. A final approved version is available as a draft. If publication can take more than 6 months, it may be necessary to take measures to ensure the draft version remains available. Derived Requirements: none 3.3. Post-Approval Editorial Cleanup (non-Author Editing) Task Description: Most technical publishers do an editorial review to ensure the quality of published documents. Typically this may address issues such as grammar, spelling, readability, formatting, adherence to boilerplate, document structure, proper use of keywords, etc. Since any proposed changes occur after approval, a review and signoff mechanism must usually be established to ensure that the required changes are truly editorial. Since such changes occur outside of the normal approval process, it is desirable that such changes are minimized. Most standards organizations target "light" editing due to the dangers of changing agreed text. Discussion: Within IETF, the RFC Editor does post approval cleanup review and editing. The ambition level for cleanup can vary from: o Corrections to errors only, o Light rewriting, o Significant editing of documents with less skillful WG editors, and minimal editing when the WG editors were skilled, o Rewriting of all documents to the dictates of a style manual At times in the past year, stylistic editing has resulted in a substantial number of changes in many documents. These changes must then be vetted by all the authors followed by subsequent rounds of author acceptance and re-vetting. This can add up to a substantial delay in the publication process which must be weighed against the incremental gain in communication improvement accomplished by the cleanup. Changes to improve readability (or possibly even grammar) can end up inadvertently affecting consensus wording or technical meaning. Note that pre-approval editing to some extent avoids this problem. In specific instances it may be necessary to require that text be published "verbatim" even if doing so introduces what is perceived as Mankin & Hayes Expires November 8, 2006 [Page 7] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 poor readability or stylistic inconsistency. Examples of this include: - "Boilerplate" agreed on in an IETF working group to apply to all instances of derivative works (e.g., IANA registration documents, MIBs, etc.) - Text referring to other organizations' work - which has been carefully phrased and arranged with representatives of that other organization to deal with some politically sensitive issue. If pre-approval editing or review is done it may be possible to greatly reduce or even eliminate entirely the post-approval editing task. Pre-approval editing is generally more efficient since a separate change control process is not required. Derived Requirements: o Req-POSTEDIT-1 - The IETF technical publisher should review the document for grammar, spelling, formatting, alignment with boilerplate, document structure, proper use of keywords, etc. The review should strive to maintain consistency in appearance with previously published documents. o Req-POSTEDIT-2 - All changes made to post-approval documents should be tracked and the changes must be signed off on by the appropriate technical representatives as defined in the IETF processes. o Req-POSTEDIT-3 - The IETF Technical editor should refrain from stylistic changes that introduce a substantial review load but only provides incremental increase in the clarity of the specification. Specific guidelines on the types of changes allowed may be further specified, but ultimately restraint in editing must be imposed by the IETF technical publisher. Changes for stylistic consistency should be done only when there are major problems with the quality of the document. o Req-POSTEDIT-4 - The IETF Technical editor should refrain from changes to improve readability that may change technical and consensus wording. Specific guidelines on the types of changes allowed may be further specified, but ultimately restraint in editing must be imposed by the IETF technical publisher. Mankin & Hayes Expires November 8, 2006 [Page 8] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 o Req-POSTEDIT-5 - In specific instances, where some or all of document text is the result of a careful negotiation of contributions (within or between working groups, reviewers, etc.), the IESG or IAB or IRSG will require that the publisher publish that text verbatim. It is the expectation of the IETF community that this will not be done often. 3.4. Validation of references Task Description: Most standards organizations require that normative references be publicly available. Some technical publishers verify the validity and availability of references (included referenced clauses and figures). Although some editorial clean-up of references may be obvious, the issue becomes more severe when reference links are broken, are not publicly available, or refer to obsoleted documents. Such faults may be viewed as a post-approval fault found in the document. Most publishers have the ability to put a document on hold awaiting the publication of a reference expected to be available soon. Discussion: The RFC Editor may put a document on hold waiting for the availability of other IETF documents. Incorrect references are handled like any other fault detected in the editorial review. Derived Requirements: o Req-REFVAL-1 - The IETF technical publisher should ensure that references within specifications are available. o Req-REFVAL-2 - The IETF technical publisher should delay publication until all required IETF references are ready for publication. 3.5. Validation of formal languages Task Description: If the Specification contains a formal language section (such as a MIB), the technical publisher may be required to validate this using a tool. Discussion: The RFC Editor validates sections of a document containing MIBs, ABNF, XML, and possibly other formal languages. Derived Requirements: o Req-FORMALVAL-1 - The IETF technical publisher should validate sections of documents containing formal languages. In particular ASN.1, ABNF, and XML should be verified using appropriate tools. Mankin & Hayes Expires November 8, 2006 [Page 9] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 3.6. Insertion of Parameter Values Task Description: The Technical Publisher is expected to work with IANA (or possibly other organizations maintaining registries) to populate protocol parameters when required prior to publication. The population of these parameters should not require technical expertise by the technical publisher. Discussion: Within IETF, IANA normally does its allocations as an early step in the technical publication. Derived Requirements: o Req-PARAMEDIT-1 - The IETF technical publisher should work with IANA in the population of required parameter values into documents. 3.7. Post Approval, Pre-Publication Technical Corrections Task Description: Regardless of efforts to minimize their occurrence, it is always possible that technical flaws will be discovered in the window between document approval and publication. The technical publisher may be requested to incorporate technical changes into the document prior to publication. Such changes necessitate a review and sign-off procedure. Another option is to disallow such corrections and treat them as you would post-publication errata. Note that this task is distinct from post approval changes that might originate due to editorial review because they originate from outside the technical publisher. For severe flaws, it should always be possible to withdraw the document from the publication queue. Discussion: IETF allows minor technical corrections during the publication process. This should ideally be a rare occurrence. Since any changes introduced during the post-approval phase can lead to publication delays it is important that only changes with technical merit be permitted. In particular stylistic changes should be discouraged. IETF processes must be in place to vet changes proposed by the author, but this is not specifically a requirement on the technical publisher. The interaction between the authors and the technical publisher must be sufficiently well policed that untracked and unapproved changes cannot be introduced by the author or other parties. Derived Requirements: Mankin & Hayes Expires November 8, 2006 [Page 10] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 o Req-POSTCORR-1 - The IETF technical publisher should permit the incorporation of technical changes detected after approval, but pre publication. o Req-POSTCORR-2 - The IETF technical publisher should only allow post approval technical changes which have been approved by the appropriate IETF party (often the document shepherd, but sometimes, by referral, the IESG). o Req-POSTCORR-3 - The publisher should alert the IESG (or IAB or IRSG) when it feels that a requested change is unreasonable. Further processing of the draft should be suspended pending a response by the IESG (or IAB or IRSG) on how to proceed. o Req-POSTCORR-4 - The IETF technical publisher should ensure that any source documents associated with a publication are also updated in concert with their associated specifications. 3.8. Allocation of Permanent Stable Identifiers Task Description: For a document to be referenced, it must have a unique permanent identifier. In some standards organization, it is the technical publisher that generates this identifier. In other cases the identifier may be allocated earlier in the process. Discussion: Currently, the RFC Editor allocates these numbers when the document is near the end of the publication process. Having identifiers allocated early was considered, but a definite need could not be established. Derived Requirements: o Req-PERMID-1 - The IETF technical publisher should allocate stable identifiers as part of the publication process. o Req-PERMID-2 - The IETF technical publisher should assign additional permanent identifiers associated with various classes of documents as directed by the IETF. 3.9. Document Format Conversions Task Description: The technical publisher is responsible for converting the documents into one or more output formats (text, pdf, ps, etc.). In some standards organizations, the technical publisher may be required to accept input documents in various formats and produce a homogeneous set of output documents. Mankin & Hayes Expires November 8, 2006 [Page 11] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 Discussion: Currently, the RFC Editor accepts input as an ascii text file (supplemented by xml if available). The documents are published as ascii text, postscript, and pdf files. Derived Requirements: o Req-DOCCONVERT-1 - The IETF technical publisher should accept as input ascii text files and publish documents as ascii text files, postscript files, and pdf files. o Req-DOCCONVERT-2 - The technical publisher should accept supplemental source files that may contain information such as: code, formal descriptions (XML, ASN.1, etc.) graphics, data files, etc. 3.10. Language Translation Task Description: Some standards organizations require publication of documents in multiple languages. This translation is the responsibility of the technical publisher. Discussion: IETF specifications are published only in English. Derived Requirements: none 3.11. Publication Status Tracking Task Description: The technical publisher should have the ability to provide status information on the status of a document. This may involve developing a process model or a checklist and providing information on a document's state, outstanding issues, and responsibility tokens. Depending on the need for transparency, this information may need to be available online and continuously updated. Discussion: The RFC Editor currently provides status information via the RFC editor queue. Each document is attributed a status (AUTH48, RFC-EDITOR, IANA, ISR, etc.) Items may stay on the queue for a long time without changing status. This status tracking information is not integrated with the IESG tracking tools. Within the IETF, the PROTO team is considering requirements for marking the token-holder accurately during long waiting periods, and others are looking into improved notification tools. Requirements on the IETF technical publisher for improved status integration and visibility could be met by collaborations with these efforts, or by providing public access to email logs regarding publications, or by some other proposal. Derived Requirements: Mankin & Hayes Expires November 8, 2006 [Page 12] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 o Req-STATUSTRK-1 - The IETF technical publisher should provide state information for each document in the publication process. o Req-STATUSTRK-2 - The IETF technical publisher should integrate its state information with the IETF tools to provide end-to-end status tracking of documents. IETF documents should be able to move seamlessly from the IETF tracking system into the technical publication tracking system. o Req-STATUSTRK-3 - The IETF technical publisher should provide external visibility of not only the fact that a document is in an extended waiting period, but also the token-holder and circumstances of the wait. 3.12. Expedited Handling Task Description: In some cases (such as when the documents are needed by another standards body), it should be possible for the approving organization to request expedited publication of a document. Ideally, this should not skip any of the publication steps, but allocates it higher priority in the work queue to ensure earlier publication than normal. Expedited publication should be used sparingly since as with any priority scheme, overuse will negate its benefits. Discussion: The fast-tracking procedure is used to expedite publication of a document at the request of the IESG. Fast-tracking is generally employed when an external organization has a looming publication deadline and a need to reference a document currently in the RFC editors queue. Having short publication times would likely reduce the need for fast-tracking. Since fast tracking is disruptive to the workflow it is recommended that expedited handling be phased out as soon as alternative ways of achieving timely publication are in place. Derived Requirements: o Req-EXPEDITE-1 - The IETF technical publisher shall expedite the processing of specific documents at the request of the IESG. 3.13. Exception Handling Task Description: It should be possible for various reasons for a document to be withdrawn from publication or the publication put on hold. Reasons for this could be due to an appeals process, detection Mankin & Hayes Expires November 8, 2006 [Page 13] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 of a serious technical flaw, or determination that the document is unsuitable for publication. Discussion: For various reasons a document can be withdrawn before publication. Derived Requirements: o Req-EXCEPTIONS-1 - The IETF technical publisher should permit documents to be withdrawn from publication at the direction of the IETF. o Req-EXCEPTIONS-2 - The IETF technical publisher should permit documents to be put on hold awaiting the outcome of an appeal. 3.14. Notification of publication Task Description: The technical publisher should provide a mechanism for alerting the community at large of the availability of published documents. Discussion: The RFC Editor notifies of document publication on the rfc-dist and ietf-announce mailing lists. o Req-PUBNOTIFY-1 - The IETF technical publisher should announce the availability of published documents. 3.15. Post Publication Corrections Task Description: If corrections are identified after publication, the technical publisher should be able to publish errata that can be linked with the original document. Discussion: The RFC Editor maintains a list of errata. Pointers to relevant errata are presented as output from the RFC Editor search engine. Derived Requirements: o Req-ERRATA-1 - The IETF technical publisher should maintain errata for published documents. o Req-ERRATA-2 - The IETF technical publisher should provide information on relevant errata as part of the information associated with a RFC. Mankin & Hayes Expires November 8, 2006 [Page 14] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 3.16. Indexing: maintenance of the catalog Task Description: The technical publisher normally provides and maintains the master catalog of publications of that organization. As the publishers of the organization's output, the technical publisher is expected to be the definitive source of publications and maintainer of the database of published documents. This also includes the cataloging and storage of meta-information associated with documents such as its history, status (updated, obsoleted, etc.), document categories (standard, draft standard, bcp, individual submission etc.) Discussion: The RFC Editor maintains the catalog. The RFC editor is also responsible for the permanent archival of specifications. Meta information associated with an RFC should also be maintained. Since this is the definitive archive, sufficient security should be in place to prevent tampering with approved documents. o Req-INDEX-1 - The IETF technical publisher should maintain the index of all IETF published documents. o Req-INDEX-2 - The IETF technical publisher should provide the permanent archive for published documents. o Req-INDEX-3 - Meta information associated with a published document must be stored and updated as its status changes. o Req-INDEX-4 - The archive must be sufficiently secure to prevent the modification of published documents by external parties. o Req-INDEX-5 - The IETF technical publisher should provide the permanent archive of any source documents associated with a published specification. o Req-INDEX-6 - The IETF can indicate to the publisher that it should change the status of a document (e.g., to Historical) and this should be reflected in the index. o Req-INDEX-7 - The IETF can indicate to the publisher that it should purge a document from the index. This should remove all traces of the document. 3.17. Access to Published Documents Task Description: The technical publisher should facilitate access to the documents published. It is assumed that the technical publisher will provide online tools to search for and find information within Mankin & Hayes Expires November 8, 2006 [Page 15] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 the archive of published documents. These access tools should facilitate understanding the state of the document (identification of replacement or updated documents, linkage to pertinent errata) Discussion: Documents and status may be accessed via the RFC Editor's web page Derived Requirements: o Req-PUBACCESS-1 - The IETF technical publisher should provide search tools for finding published documents o Req-PUBACCESS-2 - The IETF technical publisher tool should return relevant meta information associated with a published document (e.g., category of document, type of standard (if standards track), obsoleted by or updated by information, associated errata) o Req-PUBACCESS-3 - The IETF Technical Publication search tools should be integrated with the IETF search tools. 3.18. Maintenance of a Vocabulary Document Task Description: Some standards organizations require the technical publisher to maintain a publicly available vocabulary document or database containing common terms and acronyms. The goal is provide consistency of terminology between documents. Discussion: The RFC Editor does not maintain a public document or database of terms or acronyms. Derived Requirements: none 3.19. Providing Publication Statistics and Status Reports Task Description: The technical publisher may be required to periodically or continuously measure their performance. In many standards organizations performance targets are set in terms of timeliness, throughput, etc. Discussion: The IETF technical publisher currently provides monthly statistics on arrivals and completions of documents by category. In addition a status report is provided at each IETF meeting. Derived Requirements: Mankin & Hayes Expires November 8, 2006 [Page 16] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 o Req-STATS-1 - The IETF technical publisher should provide monthly statistics on average queue times and documents processed sorted by category of document. The presentation should provide a historical context to identify trends (see Req-THROUGHPUT-3). o Req-STATS-2 - The IETF technical publisher should provide periodic status reports to the IETF meetings to apprise the community of their work and performance. 3.20. Process and Document Evolution Task Description: The guidelines and rules for an organization's publication output will change over time. New sections will be added to documents, styles and conventions will change, boilerplate will be changed, etc. Similarly, the specific processes for publication of a specification will change. The technical publisher is expected to be involved in these discussions and accommodate these changes as required. Discussion: Over time, the IETF consensus on what should be in a published document has changed. Processes interfacing with the publisher have also changed. Such changes are likely to continue in the future. The RFC editor has been involved in such discussions and provided guides, policies, faqs, etc. to document the current expectations on published documents. Derived Requirements: o Req-PROCESSCHG-1 - The IETF technical publisher should participate in the discussions of changes to author guidelines and publication process changes. o Req-PROCESSCHG-2 - The IETF technical publisher should participate in and support process experiments involving the technical publication process. 3.21. Tutorial and Help Services Task Description: The technical publisher may be required to provide tutorials, mentoring, help-desks, online tools, etc. to facilitate smooth interaction with the technical publisher and IETF community awareness of document guidelines, procedures, etc. In many organizations the publisher maintains a style manual giving explicit guidance to authors on how to write a specification. Mankin & Hayes Expires November 8, 2006 [Page 17] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 Discussion: Guidelines are provided to the authors on how to write a RFC as well as occasional tutorial presentations. The RFC Editor provides a help desk at IETF meetings. Derived Requirements: o Req-PUBHELP-1 - The IETF technical publisher should provide and maintain documentation giving guidance to authors on the layout, structure, expectations, etc. required to develop documents suitable for publication. The technical publisher should follow IETF guidance in specifying documentation guidelines. o Req-PUBHELP-2 - The IETF technical publisher should provide tutorials to the IETF community to educate authors on the processes and expectations of the IETF technical publisher. o Req-PUBHELP-3 - The IETF technical publisher shall provide a contact e-mail address and correspond as required to progress the publication work. The publisher should address queries from both inside and outside of the IETF community. 4. Technical Publisher Performance Metrics A Technical Publisher is typically measured not only on what they do but how well they perform the tasks. Here are some metrics that could apply to the IETF technical publisher. 1. Post-approval timelines 2. Publication throughput 3. Non author changes generated during publication 4. Author changes generated during publication 4.1. Post-approval timeframes Metric Description: This is a statistical measure of the time from entry into the RFC editor queue (via IESG approval, individual submission, etc.) until the documents are published. The statistics should be separated by categories of documents. It may be desirable to also provide statistics along the distribution curve (90% completed within x weeks, 95% completed within y weeks, etc.) Discussion: Long publication times create both internal and external difficulties. Internal difficulties include the migration of authors to other activities and the accumulation of tempting post-approval Mankin & Hayes Expires November 8, 2006 [Page 18] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 fixes to be added to the document. External difficulties include the inability of other standards organizations to reference IETF publications for lack of a RFC number. Derived Requirements: o Req-TIMEFRAMES-1 - The consensus of the IETF community is that an average publication time of under a month is desirable. It is understood that in some cases there will be delays outside of the publisher's control. The actual performance targets and metrics are expected to be determined as part of the contract negotiation process. o Req-TIMEFRAMES-2 - The consensus of the IETF community is that the time required for a pre-publication review should be under 10 days. The actual performance targets and metrics are expected to be determined as part of the contract negotiation process. 4.2. Publication Throughput Metric Description: The count of documents published during a given time period. Some publishers also provide the data in terms of pages produced. The counts should be separated by categories of documents. Discussion: The RFC currently provides monthly statistics on the arrival and completion of documents onto the RFC queue. This is sorted by category of document. Derived Requirements: o Req-THROUGHPUT-1 - The IETF technical publisher should provide monthly reports giving RFC queue arrivals, completions, and documents on the queue sorted by document source of the document (IAB, IESG, individual submission) o Req-THROUGHPUT-2 - The IETF technical publisher should indicate the number of documents in each state at the end of each month sorted by document source category. o Req-THROUGHPUT-3 - Although minor variations are expected, there should be no long term growth trend in the length of the publication queue. 4.3. Non author changes Generated during Publication Metric Description: To judge the effectiveness of the editorial review and comment resolution, it is useful to provide aggregate Mankin & Hayes Expires November 8, 2006 [Page 19] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 statistics on post approval changes generated (separated by type of error) as well as the resolution of the comments (% rejected) Discussion: To understand trends in the types of errors occurring and how editing effort is being expended, it is useful to gather aggregate statistics on the types of errors being uncovered by the editors. Derived Requirements: o Req-EDITCHGSTATS-1 - The IETF technical publisher should provide monthly statistics on the types of editorial corrections being found during reviews as well as the percent of corrections which are rejected by the authors. 4.4. Author changes generated during publication Metric Description: To judge the stability of documents during the publication process it is desirable to provide aggregate statistics on the number and type of changes introduced by the authors after document approval. This category also includes changes made by Area Directors or other persons (outside of the technical publisher) empowered to make changes. Discussion: This provides a measure of the stability of the documents and can indicate if the delays in publication are leading to excessive changes in the documents. Derived Requirements: o Req-AUTHCHGSTATS-1 - The IETF technical publisher should provide monthly statistics on author (or other persons outside of the technical publisher empowered to make changes) requested changes to documents under publication. 5. IETF Implications of Technical Publication Requirements Requirements on technical publication process have so far been stated in terms of requirements on the technical publisher. However it must be recognized that many of these requirements have implications on the processes and tools within the IETF itself. It is anticipated that these processes will be documented in companion documents which will be generated by various bodies within the IETF. The following is a list of potential issues that should be addressed within the IETF based on the requirements applied to the technical publisher: Mankin & Hayes Expires November 8, 2006 [Page 20] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 o Pre- vs Post-Approval Editing: If emphasis switches from post- approval editing to pre-approval editing, then IETF processes must be adapted to make use of this service. The processes for post- approval editing can also be streamlined. o Post Approval Editorial Cleanup: IETF must define under what conditions the publisher should be instructed to bypass or minimize post approval editing. o Approval of post-approval, pre-publication technical corrections: Since the technical publisher can only accept approved changes, it must be clear who is allowed to approve technical changes. This process within the IETF needs to be decided and documented. o Allocation of Permanent Stable Identifiers: IETF needs to clearly identify the naming/numbering schemes and classes of documents to which those names and numbers apply. Furthermore, the responsibility for allocation of those names/numbers needs to be identified. o Expedited Handling: If publication timelines can be reduced sufficiently, then expedited handling may no longer be needed. o Post Publication Corrections: Appropriate processes must be defined with the IETF to ensure that errata is appropriately vetted and authorized. o Indexing: Appropriate processes must be defined within the IETF to decide and inform the technical publisher of status changes to published documents as the result of an appeal, legal action, or some other procedural action. 6. IANA Considerations Any new 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. Interactions with IANA on parameter validation is discussed in section 3.6. 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. As with other text, extreme caution is needed in modifying any text in the security Mankin & Hayes Expires November 8, 2006 [Page 21] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 considerations. This issue is assumed to have been dealt with under the section 3.3. The processes for the publication of documents must prevent the introduction of unapproved changes (see section 3.7). Since the IETF publisher maintains the index of publications, sufficient security must be in place to prevent these published documents from being changed by external parties (see section 3.16) 8. Acknowledgments Bert Wijnen has provided input on the early copy edit experiment and made useful comments throughout the document. Leslie Daigle has contributed strongly to this text. Thanks to Steve Barclay, John Meredith, Yvette Ho Sang, and Sami Trabulsi for discussions of the publication practices of ATIS, ETSI, IEEE, and ITU. Other acknowledgements to date: a discussion on the wg chairs mailing list, Henning Schulzrinne, Henrik Levkowetz. Author's Addresses Allison Mankin Washington, DC USA Phone: +1 301 728 7199 Email: mankin@psg.com URI: http://www.psg.com/~mankin/ Stephen Hayes Ericsson 3634 Long Prairie Rd. Ste 108-125 Flower Mound, TX 75022 USA Phone: +1 469 360 8500 Email: stephen.hayes@ericsson.com 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 Mankin & Hayes Expires November 8, 2006 [Page 22] Internet-Draft draft-mankin-techspec-pub-req-08 May 2006 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 (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Mankin & Hayes Expires November 8, 2006 [Page 23]