Editor Intro IETF59 Seoul, ROK 2004
Editor IntroEditor Intro
IETF59
Seoul, ROK
2004
This SessionThis Session
Please let me know if this talk meets • your expectations• your needs
recommendations for improvement to:
• [email protected] • [email protected]
https://www1.ietf.org/mailman/listinfo/edu-discuss • Education Team Web Page: edu.ietf.org
Goals and non goalsGoals and non goals
• Goals Gather information about RFC editorship in one
place Disseminate information so that quality can
become more balanced.
• Non Goal Will not explain everything in detail Not a class in technical writing
OverviewOverview
• 3Rs of IETF Editorship Role of the editor in the WG Responsibilities of the editor Rights of the editor
• Constraints
• Tools
• RFC End Game
RoleRole
• Work to achieve rough consensus in the text with other WG participants, with design teams with chairs
• Produce timely updates containing agreed upon, or agreeable, text.• Produce a document that meets all the
constraints established for an RFC
ResponsibilitiesResponsibilities
• Translate the rough consensus of the WG into text
• Produce technically accurate text
• Produce technically lucid text
• Produce well formed English text
• Produce a well formed document, I.e. a document that meet the requirements laid out for RFCs.
RightsRights
• Questions: Can the editor decide on content? Can the editor decide when the doc is ready for
last call? Can the editor control the language usage? What can the editor decide on his or her own? Can the editor be replaced?
Content DecisionContent Decision
• NO for overriding WG decisions
• YES for straw man proposals or "filling in details" from a WG decision But
Editor must be careful to not create a ‘fait accompli’ with proposals that have not yet been adequately reviewed by the WG
Editor must be careful in the demons that lurk in details
Last Call DecisionLast Call Decision
• No - it is not up to the Editor to make the decision
• Works with the WG chair to enable the chair to make this determination Though: "I have more nits to fix" can influence the
decision strongly
Language UsageLanguage Usage
• Language is a complicated subject Editor can certainly pick which form of correct
English language to use. I.e. could be The Queen’s English or American Standard or …• Unless, perhaps, they are picking up the work of
another editor in which case consistency becomes more important.
Word and Phrase ChoiceWord and Phrase Choice
Choice of words, however, can be very very complicated and is often a barrier to making progress with an otherwise complete document• for language reasons
Idiomatic speech
• for technical reasons can’t assume everyone has same understanding of terms some words have specific defined usage
• Key words for use in RFCs to Indicate Requirement Levels (RFC 2119)
• for techno-political reasons I.e. word choice is often a content decision not just an editorial
decision
Editorial DecisionsEditorial Decisions
• Editor has leeway when creating the document to choose a structure that will meet the requirements of the WG.
• The editor is not a scribe who waits to be told what words to write. It is the editor’s responsibility to create, or incorporate text that meets the WG’s intentions and requirements
• But the editor is not an independent author• In the end the WG itself controls all decisions.
Editors and AuthorsEditors and Authors
• Often someone who is the author of an independent draft becomes the editor of a WG draft.
• This involves a radical change in roles
• And can be very difficult because it means giving up change control of the document
• Often original authors are not the best lead editors
Editor ReplacementEditor Replacement
• It is the WG chair’s option to choose the editor
• and to replace the editor
ConstraintsConstraints
• A well formed RFC starts with a well formed I-D
• Essential References The Internet Standards Process -- Revision 3 (RFC 2026) Key words for use in RFCs to Indicate Requirement Levels
(RFC 2119) Guidelines for Writing RFC Text on Security Considerations (
RFC 3552 )
Guidelines for Writing an IANA Considerations Section in RFCs (RFC2434)
• IESG review Surviving nit patrol:
AD Review of I-Ds (www.ietf.org/ID-nits.html)
ConstraintsConstraints
• Use of Formal Languages Guidelines for the use of formal languages in IETF specifications
www.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txt
• MIBs in RFCs Guidelines for MIB Authors and Reviewers
www.ietf.org/internet-drafts/draft-ietf-ops-mib-review-guidelines-02.txt
GuidelinesGuidelines
• A good start is to get a well formed Internet Draft www.ietf.org/ietf/1id-guidelines.txt
• Guidelines to authors of Internet-drafts ftp://ftp.rfc-editor.org/in-notes/rfc-editor/
instructions2authors.txt
currently: draft-rfc-editor-rfc2223bis-07.txt Definitive guidance for the RFC editor
Guidelines cont’dGuidelines cont’d
• General RFC Editorial Policies Immutability Not all RFC’s are standards Language - all RFCs in English• RFC2026 allows for translations
Consistent Publication Format• ASCII (also .txt.pdf)• Also .ps or .pdf (special process for handling)• Assignment of RFC number - late in process
Guideline cont’dGuideline cont’d
• General RFC Editorial Policies (cont’d) References• Normative• Informative• Recommendations on reference numbering
URL use is discouraged Recommendation on Titles• No Abbreviations - except for the most well
known (e.g. IP, TCP …)
Guidelines cont’dGuidelines cont’d
• General RFC Editorial Policies (cont’d) Relation to other RFCs
• Updates• Obsoletes
Authors• Limited to lead authors or editors• While not strictly limited, there will need to be very good reason to
list more the 5• All authors equally responsible for 48 hours review• Authors section should provide unambiguous contact points• Others can be included in contributor and acknowledgement
sections
Guidelines cont’dGuidelines cont’d
• General RFC Editorial Policies (cont’d) April 1 RFCs - Most but not all are satirical
documents. These are reviewed for cleverness, humor and topical relation to IETF themes
A favorite quote from Instructions2authors.txt (RFC2223bis)
Note that in past years the RFC Editor has sometimes published serious documents with April 1 dates. Readers who cannot distinguish satire by
reading the text may have a future in marketing.
Guidelines cont’dGuidelines cont’d
• General RFC Editorial Policies (cont’d) IPR rights issues
• Copyright Issues• Technology Use Issues• Specified in
RFC3667IETF Rights in Contributions
RFC3668Intellectual Property Rights in IETF Technology
RFC3669Guidelines for Working Groups on Intellectual Property Issues
• Provides rules for general formatting of RFC Including Protocol data descriptions
Guidelines cont’dGuidelines cont’d
• Sections of an RFC - with descriptions 1. First-page header [Required] 2. Status of this Memo [Required*] 3. Copyright Notice [Required*] 4. IESG Note [As requested by IESG*] 5. Abstract [Required] 6. Table of Content [Required for large documents] 7. Body of the Memo [Required] 7a. Contributors 7b. Acknowledgments 7c. Security Considerations [Required] 7d. IANA Considerations 7e. Appendixes 7f. References 8. Author's Address [Required] 9. Full Copyright Statement [Required*]
RFC2026RFC2026
• Defines the IETF Standardization process
• Defines maturity levels
• Defines Tracks Experimental Informational Historical Standards Best current Practices
• WG Process
RFC2026 cont’dRFC2026 cont’d
• Defines process for action on a document Must be a Internet Draft for at least 2 weeks Unless based on an RFC that has not changed Must be initiated by a WG for things that are WG
work items
• Must be reviewed by IESG• Then is passed on the RFC editor
Once it is passed on, and I-D does not expire
• RFCs are unchanging once published Status can be changed but not the content
RFC2119RFC2119
• Defines use of words in Standards MUST, MUST NOT (REQUIRED, SHALL) SHOULD, SHOULD NOT (RECOMMENDED) MAY, MAT NOT (OPTIONAL)
• Gives guidance on use of imperatives Use sparingly
• required for interoperation• limit harmful behavior
Not to impose methods on implementers
RFC 3552 - SecurityRFC 3552 - Security
• Covers the goals of security
• contains recommendations on writing security considerations All RFCs must have a security considerations
section. Includes Examples
• Recommend attending Security later today 15.00 - 17.00
NITSNITS
• www.ietf.org/ID.nits.html Form Nits Content Issues, including:
• Security, IPR, RFC2119 words• Internationalization of visible fields
IETF Policy on Character Sets and Languages RFC2277
• Use of code in documents• Addresses• References
Protocol Issues, including:• V4/V6• No causing catastrophic congestions• Be precise about checksum or integrity check
Use of Formal LanguagesUse of Formal Languages
• http:// www.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txt ftp.rfc-editor.org/in-notes/rfc-editor/UsingPseudoCode.txt
• While formal languages are useful, there is no one formal language that can capture all syntax and semantics. Therefore, English remains the primary method of describing protocols.
• Formal languages and pseudocode are useful as an aid in explanations
• Pseudocode Clarity is the goal and the pseudocode will be judged on that basis
• Formal Languages (e..g C, ASN.1, XML) Requires normative reference of specification for the language Language most be used properly Specification must be complete and verifiably correct Specification must attempt to be implementation neutral Does not need to be a reference implementation
IANA considerationsIANA considerations
• Guidelines for Writing an IANA Considerations Section in RFCs (RFC2434) Need to provide procedure for ways that all extensible
numbered fields are to be handled Attention must be paid to size of name space Must provide policy for delegation of specific name spaces
and ranges within those name spaces.• Private use, Hierarchical Allocation, First Come First Served,
Expert Review, Specification Required, IESG Approval, IETF Consensus, IETF Standard
Guidelines in RFC should allow IANA to control the name space according to the consensus of the WG and IETF without needing to consult for that consensus - unless of course the name space or some part of it requires explicit consultation.
draft-ietf-ops-mib-review-guidelinesdraft-ietf-ops-mib-review-guidelines
• MIB boilerplate section
• Narrative sections
• Definitions section
• Intellectual Property section
• All MIBS must pass compilation
ToolsTools
• Text formatting toolswww.rfc-editor.org/formatting.html xml2rfc nroff microsoft word templates LaTeX
• MIB reference and compilers
xml2rfcxml2rfc
• www.ietf.org/rfc/RFC2629.txt - M. Rose Writing I-Ds and RFCs using XML Explains use of DTD for RFC production Includes DTD http://xml.resource.org/ xml2rfc resources
• Updates• DTD• Conversion tools• Online conversion tool• Bibliographic references
xml2rfc mailing list [email protected]://lists.xml.resource.org/mailman/listinfo/xml2rfc
nroff, goffnroff, goff
• 2-nroff-templates Published in 1991 - J. Postel Gives instructions on using macros for creating
RFCs ftp.rfc-editor.org/in-notes/rfc-editor/2-nroff.template David Meyer maintains an updated nroff template
www.1-4-5.net/~dmm/generic_draft.tar.gz
microsoft word templatesmicrosoft word templates
• 2-word-template.doc Published in 2002 - T. Hain Using Microsoft Word to create Internet Drafts and
RFCs www.ietf.org/rfc/rfc3285.txt
Template can be found at:• ftp.ietf.org/internet-drafts/2-Word.template.rtf• ftp.ietf.org/internet-drafts/crlf.exe• ftp.rfc-editor.org/in-notes/rfc-editor/2-Word.template.rtf• ftp.rfc-editor.org/in-notes/rfc-editor/crlf.exe
LaTeLaTe
• Mostly private templates and methods
• Sometimes causes difficulty when documents are inherited by new authors.
• Tool for conversion of LaTeX to text www.cs.columbia.edu/IRT/software/l2x/
MIB ToolsMIB Tools
• MIB reference and tools O&M Web Site at www.ops.ietf.org/
http://www.ops.ietf.org/mib-review-tools.html smilint at www.ibr.cs.tu-bs.de/projects/libsmi/ SMICng at www.snmpinfo.com/ MIB doctors at www.ops.ietf.org/mib-doctors.html
RFC End GameRFC End Game
• Once you think you are done
there is a long way to go yet.
WG Last Call IESG Review Final Process
WG Last CallWG Last Call
• Called by WG chair
• Optional but traditional
• 1st one usually lasts for at least 2 weeks
• Document should be extensively reviewed both within the WG and across other areas
• Substantive changes to the document often warrant a second WG Last Call WG chair decision
• Can be shorter• Can be restricted to issues brought up and resolved from previous
last call
IESG ReviewIESG Review
2 week IETF Last Call for Standards Track and BCP Documents and sometimes Experimental and Informational
RFC Editor Review• Look so see if guidelines have been met
Preliminary IANA Review• Looks at IANA consideration to start figuring out the namespaces
that will need to IANA managed. IESG Cross discipline Review
• Take IETF Last Call comments into account• Can decide to pass document on for publication• Decides on track for document• Can send document back to WG with comments and DISCUSS
issues which must be resolved before the document proceeds to RFC
• Can reject a document
Final ProcessFinal Process
Editor(s)• Send RFC Editor NROFF or XML source• Send RFC Editor any updates, especially Editor contact
info and known editorial changes.
RFC Editor• Create official NROFF Source• Works with Editors on any issues• Assigns RFC number
IANA review• Creation of IANA database
48 Hour review48 Hour review
48 Review• Last minute changes - as long as not technically
substantive• Last ever changes • All Editors must sign off on final document before
release• This process can involve a fair amount of work over a
short period.• Critical that editors take it seriously -
Review the entire document not just the diffs
ErrataErrata
• From: www.rfc-editor.org/errata.html Published RFCs never change. Although every
published RFC has been submitted to careful proof reading by the RFC Editor and the author(s), errors do sometimes go undetected. As a service to the readers of RFCs, this page contains a list of technical and editorial errors that have been reported to the RFC
Editor and verified by the authors or the IESG. To report typos in published RFCs, please send email to rfc-
[email protected]. To report suspected errors that are more technical in nature, please verify the errors with the authors and/or appropriate area directors of the IESG before sending them to the RFC Editor for posting.