One document matched: draft-mankin-pub-req-03.txt
Differences from draft-mankin-pub-req-02.txt
Network Working Group A. Mankin
Internet Draft Shinkuro, Inc
Expires: July 2006 S. Hayes
Ericsson
January 16, 2006
Requirements for IETF Technical Publication Service
draft-mankin-pub-req-03.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 July 16, 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 July 16, 2006 [Page 1]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
Conventions used in this document
Requirements are designated as either current requirements (Current
Req-xx) to indicate requirements that seem to currently exist and
potential requirements (Potential Req-xx) to indicate requirements
that are speculative.
Table of Contents
1. Introduction...................................................3
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..................................8
3.5. Validation of formal languages............................9
3.6. Assignment of Parameter Values............................9
3.7. Post Approval, Pre-Publication Technical Corrections......9
3.8. Allocation of Permanent Stable Identifiers...............10
3.9. Document Format Conversions..............................11
3.10. Language Translation....................................11
3.11. Publication Status Tracking.............................11
3.12. Expedited Handling......................................12
3.13. Exception Handling......................................13
3.14. Notification of publication.............................13
3.15. Post Publication Corrections............................13
3.16. Indexing: maintenance of the catalog....................14
3.17. Access to Published Documents...........................15
3.18. Maintenance of a Vocabulary Document....................15
3.19. Providing Publication Statistics and Status Reports.....15
3.20. Process and Document Evolution..........................16
3.21. Tutorial and Help Services..............................16
4. Technical Publisher Performance Metrics.......................17
4.1. Post-approval timeframes.................................17
4.2. Publication Throughput...................................18
4.3. Non author changes Generated during Publication..........18
4.4. Author changes generated during publication..............19
5. IETF Implications of Technical Publication Requirements.......19
6. IANA Considerations...........................................20
7. Security Considerations.......................................20
8. Acknowledgments...............................................20
9. Informative References........................................20
Author's Addresses...............................................21
Intellectual Property Statement..................................21
Mankin & Hayes Expires July 16, 2006 [Page 2]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
Disclaimer of Validity...........................................22
Copyright Statement..............................................22
Acknowledgment...................................................22
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. 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.
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:
o Policies governing the acceptable input and output document
formats (including figures, etc.),
Mankin & Hayes Expires July 16, 2006 [Page 3]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
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.)
To allow progress on developing the process requirements, this
document assumes the policies for document format, etc. as are
currently defined in [1].
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 document that update IETF protocols where
there is no longer a working group, or documents on interdisciplinary
topics.
| 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
Figure 1: Stages of a Working Group Document
Mankin & Hayes Expires July 16, 2006 [Page 4]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
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 current or potential 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. Assignment 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
17.Access to published documents
Mankin & Hayes Expires July 16, 2006 [Page 5]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
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
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 with promising
results in the early copy editing experiment.
Derived Requirements:
o Potential 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 address the areas outlined in [1].
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 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
Mankin & Hayes Expires July 16, 2006 [Page 6]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
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 40-100
substantive 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.
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 Current Req-POSTEDIT-1 - The IETF technical publisher should
review the document for grammar, spelling, formatting, adherence
to boilerplate, document structure, proper use of keywords, etc.
as defined in [1].
Mankin & Hayes Expires July 16, 2006 [Page 7]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
o Current 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 Potential 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.
o Potential 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.
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 Current Req-REFVAL-1 - The IETF technical publisher should ensure
that references within specifications are available.
o Current Req-REFVAL-2 - The IETF technical publisher should delay
publication until all required IETF references are ready for
publication.
Mankin & Hayes Expires July 16, 2006 [Page 8]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
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 Current 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.
3.6. Assignment 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 Current 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.
Mankin & Hayes Expires July 16, 2006 [Page 9]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
Discussion: IETF allows minor technical corrects during the
publication process. This should ideally be a rare occurrence, but
as publication times increase, the number of minor technical
improvements increases. 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 Current Req-POSTCORR-1 - The IETF technical publisher should
permit the incorporation of technical changes detected after
approval, but pre publication.
o Current Req-POSTCORR-2 - The IETF technical publisher should only
allow post approval technical changes which have been approved by
the IESG.
o Potential Req-POSTCORR-3 - The IETF technical publisher should
have the discretion to reject post-approval corrections as too
late in the process and propose that it be handled as errata.
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. When the
delay between technical approval and publication of a document is
long, this creates a problem for external standards organizations
that cannot reference the specification until this identifier is
available.
Derived Requirements:
o Current Req-PERMID-1 - The IETF technical publisher should
allocate stable identifiers as part of the publication process.
Mankin & Hayes Expires July 16, 2006 [Page 10]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
o Potential Req- PERMID-2 - The IETF technical publisher should
permit early allocation of stable identifiers for or by the IESG
to satisfy referencing requirements of external bodies.
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.
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 Current 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 Potential Req-DOCCONVERT-2 - The IETF technical publisher should
accept as input xml2rfc files.
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 of the queue for a long
Mankin & Hayes Expires July 16, 2006 [Page 11]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
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 [2]. 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:
o Current Req-STATUSTRK-1 - The IETF technical publisher should
provide state information for each document in the publication
process.
o Potential 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 Potential 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 expedites publication of a
document. Ideally, this should not skip any of the publication
steps, but allocates it higher priority in the work queue that should
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 or providing
stable identifiers early in the publication process would likely
reduce the need for fast-tracking.
Derived Requirements:
Mankin & Hayes Expires July 16, 2006 [Page 12]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
o Current 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
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. The RFC Editor can also deem an independent submission
as not acceptable for publication.
Derived Requirements:
o Current Req-EXCEPTIONS-1 - The IETF technical publisher should
permit documents to be withdrawn from publication at the direction
of the IESG or by the author (for independent submissions).
o Current Req-EXCEPTIONS-2 - The IETF technical publisher should
have the discretion to reject publication of an independent
submission based upon feedback from reviewers.
o Current Req-EXCEPTIONS-3 - 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 Current 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.
Mankin & Hayes Expires July 16, 2006 [Page 13]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
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 Current Req-ERRATA-1 - The IETF technical publisher should
maintain errata for published documents.
o Current Req-ERRATA-2 - The IETF technical publisher should provide
information on relevant errata as part of the information
associated with a RFC.
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 Current Req-INDEX-1 - The IETF technical publisher should maintain
the index of all IETF published documents.
o Current Req-INDEX-2 - The IETF technical publisher should provide
the permanent archive for published documents.
o Current Req-INDEX-3 - Meta information associated with a published
document must be stored and updated as its status changes.
o Current Req-INDEX-4 - The archive must be sufficiently secure to
prevent the modification of published documents by external
parties.
Mankin & Hayes Expires July 16, 2006 [Page 14]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
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
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 Current Req-PUBACCESS-1 - The IETF technical publisher should
provide search tools for finding published documents
o Current 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 Potential 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 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 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.
Mankin & Hayes Expires July 16, 2006 [Page 15]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
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:
o Current Req-STATS-1 - The IETF technical publisher should provide
monthly statistics on average queue times and documents processed
sorted by category of document.
o Current 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. 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 Current Req-PROCESSCHG-1 - The IETF technical publisher should
participate in the discussions of changes to author guidelines and
publication process changes.
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 July 16, 2006 [Page 16]
Internet-Draft draft-mankin-techspec-pubreq-02 January 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 Current 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.
o Current 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.
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
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:
Mankin & Hayes Expires July 16, 2006 [Page 17]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
o Potential Req-TIMEFRAMES-1 - The IETF technical publisher should
have an goal of 90% of documents published within x weeks of
approval. Documents held up due to references or due to a
protocol action should be excluded from this statistic.
o Potential Req-TIMEFRAMES-2 - The IETF technical publisher should
have a goal of 90% of documents have a stable identifier allocated
within y weeks of approval. Documents held up due to references or
due to a protocol action should be excluded from this statistic.
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 Current 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 Potential 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.
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
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:
Mankin & Hayes Expires July 16, 2006 [Page 18]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
o Potential 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.
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 Potential Req-AUTHCHGSTATS-1 - The IETF technical publisher should
provide monthly statistics on author 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.
The following is a list of potential issues that must be addressed
within the IETF depending on the requirements selected for the
technical publisher:
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 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 Early allocation of Permanent Stable Identifiers: If early
allocation of permanent stable identifiers is agreed as a
requirement, then the IETF processes must be adapted to either
generate or use these early identifiers.
Mankin & Hayes Expires July 16, 2006 [Page 19]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
o Exception Handling: If publication timelines can be reduced
sufficiently or permanent identifiers allocated early, then
expedited handling may no longer be needed.
It is expected that as decisions are made on the technical
publication requirements, that this section will expand to include
any associated requirements on the IETF processes.
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
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. Steve Barclay, John Meredith, and
Sami Trabulsi for discussions of the publication practices of ATIS,
ETSI, and ITU. Other acknowledgements to date: a discussion on the
wg chairs mailing list, Henning Schulzrinne, Henrik Levkowetz.
9. Informative References
[1] Reynolds, J. and Braden, R., "Instructions to Request for
Comments (RFC) Authors", draft-rfc-editor-rfc2223bis-08 (work
in progress), August 2004
Mankin & Hayes Expires July 16, 2006 [Page 20]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
[2] Levkowetz, H. and D. Meyer, "The PROTO Process: Working Group
Chair Document Shepherding", draft-ietf-proto-wgchair-doc-
shepherding-05 (work in progress), March 2005
Author's Addresses
Allison Mankin
Shinkuro, Inc.
1025 Vermont Avenue
Washington, DC 20005
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
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.
Mankin & Hayes Expires July 16, 2006 [Page 21]
Internet-Draft draft-mankin-techspec-pubreq-02 January 2006
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 July 16, 2006 [Page 22]
| PAFTECH AB 2003-2026 | 2026-04-23 13:41:53 |