Request for Comments: 4714
Category: Informational S. Hayes
Ericsson
October 2006
Requirements for IETF Technical Publication Service
Status of This Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (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.
Table of Contents
1. Introduction ....................................................2
2. Scope ...........................................................3
2.1. Stages in the Technical Specification Publication
Lifetime ...................................................4
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 ...............................12
3.10. Language Translation .....................................12
3.11. Publication Status Tracking ..............................12
3.12. Expedited Handling .......................................13
3.13. Exception Handling .......................................14
3.14. Notification of Publication ..............................14
3.15. Post-publication Corrections (errata) ....................15
3.16. Indexing: Maintenance of the Catalog .....................15
3.17. Access to Published Documents ............................16
3.18. Maintenance of a Vocabulary Document .....................17
3.19. Providing Publication Statistics and Status Reports ......17
3.20. Process and Document Evolution ...........................18
3.21. Tutorial and Help Services ...............................18
3.22. Liaison and Communication Support ........................19
4. Technical Publisher Performance Goals ..........................20
4.1. Publication Timeframes ....................................20
4.2. Publication Throughput ....................................21
5. IETF Implications of Technical Publication Requirements ........21
6. IANA Considerations ............................................22
7. Security Considerations ........................................22
8. Acknowledgements ...............................................23
9. Informative References .........................................23
1. Introduction
The work of the IETF is to discuss, develop, and disseminate
technical specifications to support the Internet’s operation.
Therefore, an important output of the IETF 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 otherwise,
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. It is
expected to be used in the preparation of future contracts. This
document is not a discussion of how well the current technical
publisher (the RFC Editor) fulfills those requirements.
2. Scope
The scope of this document is the requirements for the technical
publication process for the 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. The functions provided by the
technical publisher are sometimes referred to as editorial management
[RFC2850].
This document specifically addresses those documents published by the
IETF technical standards process. In all cases, the requirements
have been written in generic terms, so that they may be used to
express the requirements of other publication streams, elsewhere.
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 document focuses on process issues in how the IETF
technical publisher 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:
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 important aspects in
determining that the final published document is a product of the
IETF. These policies are likely to evolve as part of the ongoing
IETF dialog. The IETF technical publisher should 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
standards process. This figure shows a Working Group (WG) document
and the reviews including Working Group Last Call (WGLC), Area
Director (AD) review, IETF Last Call (IETF LC), IANA review, and IESG
review. The document shepherd (shown in the diagram as "Shepherd")
is an individual designated by the IESG to shepherd a document
through the reviews and the publication process and is often not an
AD. The lifetime is very similar for AD-sponsored IETF documents,
such as documents that update IETF protocols for which there is no
longer a working group, or documents on interdisciplinary topics.
Actors Formal Actors Actors
Reviews
| Author, | WGLC | IESG, | | IANA,
| Editor, | AD | Shepherd, | A | Tech
| IETF Sec- | IETF LC | Editor, | P | Publisher,
| retariat | IANA | WG, | P | input from
| | IESG | AD | R | authors, et al.
| | | | O |
Actions | Creation, | | Resolution | V | Non-author
| Editing, | | of all | A | editing,
| Draft Pub,| | reviews | L | other
| Tracking | | | | publication
|---------------| |---------------------| |----------------|
In WG Out of WG Post-approval
Figure 1: Stages of a Working Group Document
Note that in some cases a single submission may actually consist of
multiple source documents (supporting files, code, etc.).
Under the IETF standards process stream, the post-approval processing
is initiated by the IESG after technical approval.
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.
1. Pre-approval review or editing
2. Preliminary specification availability
3. Post-approval editorial cleanup (non-author editing)
4. Validation of references
5. Validation of formal languages
6. Insertion of parameter values
7. Post-approval, pre-publication technical 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
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
22. Liaison and communication support
For each of these tasks, we discuss its relevance to the IETF and how
it is realized within the IETF processes. Based upon this
information, we derive requirements on the IETF technical publisher.
3.1. Pre-approval Review or Editing
Task Description: This provides 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, etc.
Discussion: Pre-approval review is not part of the current IETF
standards process, but this concept has been explored in the early
copyediting experiment. Early feedback from the experiment has been
promising; however, the effectiveness of early editing is still being
evaluated.
Derived Requirements:
Req-PREEDIT-1: The IETF technical publisher should be capable of
performing an editorial review of documents early enough to allow
changes to be reviewed within the technical review process, should
the IETF choose to implement pre-approval editing. For the IETF
standards process stream, this review should be performed before WG
Last Call and provide feedback to the authors to improve the quality
of the documents. For the IETF standards process stream, the
publisher should not perform a technical review of the document.
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.
Discussion: This is not required. A final approved version is
available as an internet draft. If publication can take more than 6
months, it may be necessary to request that 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, etc. Since any
proposed changes occur after approval, a review and signoff mechanism
should 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-on text.
Discussion: Within the 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, to
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
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
and Management Information Bases (MIBs)).
- Text referring to other organizations’ work that 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
reduce or even eliminate entirely the post-approval editing task in
some cases. Pre-approval editing may be 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, etc. The review should strive to
maintain consistency in appearance with previously published
documents. In the IETF standards process stream, the publisher
should not perform a technical review of the document.
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. For the IETF standards
process stream, this includes the authors, the document shepherd
(if there is one), and the Area Director. The Area Director is
the authority for approval of all changes.
o Req-POSTEDIT-3 - The IETF technical publisher should exercise
restraint in making stylistic changes that introduce a substantial
review load but only provide an 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 publisher should exercise
restraint in making 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.
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 technical publisher may be required to publish that text
verbatim. In the IETF standards process, verbatim publication may
be requested by the IESG. 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 (including referenced
clauses and figures). Although some editorial cleanup 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 while 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 all
references within specifications are currently available and are
expected to remain available.
o Req-REFVAL-2 - The IETF technical publisher should delay
publication until all required (normative) 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 syntactically validates sections of a
document containing MIBs, Augmented Backus Naur Form (ABNF),
eXtensible Markup Language (XML), Abstract Syntax Notation One
(ASN.1), and possibly other formal languages.
Derived Requirements:
o Req-FORMALVAL-1 - The IETF technical publisher should validate the
syntax of sections of documents containing formal languages. In
particular, ASN.1, ABNF, and XML should be verified using
appropriate tools.
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 assigned protocol parameter values when required, prior to
publication. The population of these parameters values should not
require technical expertise by the technical publisher.
Discussion: Within the IETF, IANA normally does its allocations as an
early step in the technical publication process.
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 post-publication errata would be treated. 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 (see
Section 3.13).
Discussion: The 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:
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 that have been approved by the
appropriate party. In the IETF standards process stream, this
includes the authors and the Area Director. The document shepherd
(if there is one) should be kept informed of these changes.
o Req-POSTCORR-3 - The IETF technical publisher should alert the
appropriate authority when it feels that a requested change is
suspect (e.g., an unapproved technical alteration) or unreasonable
(e.g., massive editorial changes). Further processing of the
draft should be suspended pending a response by that authority.
For the IETF standards process stream, that authority is the Area
Director. If there is a document shepherd working with the Area
Director, the shepherd should be notified and kept informed as
well.
o Req-POSTCORR-4 - The IETF technical publisher should ensure that
any source documents associated with a publication are updated in
conjunction 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 organizations, 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 RFC numbers and other
identifiers (the current IETF stable identifiers) 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 appropriate authority. For the
IETF standards process stream, that authority is the IESG.
3.9. Document Format Conversions
Task Description: The technical publisher is responsible for
converting the documents into one or more output formats (e.g., text,
Portable Document Format (PDF)). 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.
Discussion: Currently, the RFC Editor accepts input as an ASCII text
file. The RFC Editor has also accepted supplementary formats that
were used to generate the ASCII text (XML and NROFF). The documents
are published as ASCII text and PDF files.
Derived Requirements:
o Req-DOCCONVERT-1 - The IETF technical publisher should accept as
：＂RFC 4714 - Requirements for IETF Technical Publication Servi＂
：＂RFC 4714 - Requirements for IETF Technical Publication Servi＂