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:

• avri@acm.org • edu-discuss@ietf.org

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 xml2rfc@lists.xml.resource.orghttp://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-

editor@rfc-editor.org. 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.

Thank youThank you

Questions?

edu-discuss@ietf.org

avri@acm.org