1. Editor Intro IETF59 Seoul, ROK 2004

2. This 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 edu-discuss@ietf.org https://www1.ietf.org/mailman/listinfo/edu-discuss Education Team Web Page: edu.ietf.org edu.ietf.org

3. Goals 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

4. Overview 3Rs of IETF Editorship  Role of the editor in the WG  Responsibilities of the editor  Rights of the editor Constraints Tools RFC End Game

5. Role 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

6. Responsibilities 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.

7. Rights 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?

8. Content 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

9. Last 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

10. Language 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.

11. Word 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

12. Editorial 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.

13. Editors 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

14. Editor Replacement It is the WG chair’s option to choose the editor and to replace the editor

15. Constraints A well formed RFC starts with a well formed I-D Essential References  The Internet Standards Process -- Revision 3 (RFC 2026) The Internet Standards Process -- Revision 3 (RFC 2026)  Key words for use in RFCs to Indicate Requirement Levels (RFC 2119) 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 RFC Text on Security Considerations ( RFC 3552 )  Guidelines for Writing an IANA Considerations Section in RFCs (RFC2434) (RFC2434) IESG review  Surviving nit patrol: AD Review of I-Ds (www.ietf.org/ID-nits.html) AD Review of I-Ds (www.ietf.org/ID-nits.html)

16. Constraints Use of Formal Languages  Guidelines for the use of formal languages in IETF specifications www.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txt 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 www.ietf.org/internet-drafts/draft-ietf-ops-mib-review-guidelines-02.txt

17. Guidelines A good start is to get a well formed Internet Draft  www.ietf.org/ietf/1id-guidelines.txt www.ietf.org/ietf/1id-guidelines.txt Guidelines to authors of Internet-drafts  ftp://ftp.rfc-editor.org/in-notes/rfc- editor/instructions2authors.txt ftp://ftp.rfc-editor.org/in-notes/rfc- editor/instructions2authors.txt  currently: draft-rfc-editor-rfc2223bis-07.txt  Definitive guidance for the RFC editor

18. Guidelines 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

19. Guideline 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 …)

20. Guidelines 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

21. Guidelines 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)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.

22. Guidelines cont’d General RFC Editorial Policies (cont’d)  IPR rights issues Copyright Issues Technology Use Issues Specified in  RFC3667 IETF Rights in Contributions RFC3667  RFC3668 Intellectual Property Rights in IETF Technology RFC3668  RFC3669 Guidelines for Working Groups on Intellectual Property Issues RFC3669 Provides rules for general formatting of RFC  Including Protocol data descriptions

23. Guidelines 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*]

24. RFC2026 Defines the IETF Standardization process Defines maturity levels Defines Tracks  Experimental  Informational  Historical  Standards  Best current Practices WG Process

25. RFC2026 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

26. RFC2119 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

27. RFC 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

28. NITS www.ietf.org/ID.nits.html  Form Nits  Content Issues, including: Security, IPR, RFC2119 wordsRFC2119 Internationalization of visible fields  IETF Policy on Character Sets and Languages RFC2277RFC2277 Use of code in documents Addresses References  Protocol Issues, including: V4/V6 No causing catastrophic congestions Be precise about checksum or integrity check

29. Use of Formal Languages http:// www.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txtwww.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txt  ftp.rfc-editor.org/in-notes/rfc-editor/UsingPseudoCode.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

30. IANA considerations Guidelines for Writing an IANA Considerations Section in RFCs (RFC2434)(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.

31. draft-ietf-ops-mib-review-guidelines MIB boilerplate section Narrative sections Definitions section Intellectual Property section All MIBS must pass compilation

32. Tools Text formatting tools www.rfc-editor.org/formatting.html www.rfc-editor.org/formatting.html  xml2rfc  nroff  microsoft word templates  LaTeX MIB reference and compilers

33. xml2rfc www.ietf.org/rfc/RFC2629.txt - M. Rose www.ietf.org/rfc/RFC2629.txt  Writing I-Ds and RFCs using XML  Explains use of DTD for RFC production  Includes DTD  http://xml.resource.org/ xml2rfc resources http://xml.resource.org/ Updates DTD Conversion tools Online conversion tool Bibliographic references  xml2rfc mailing list xml2rfc@lists.xml.resource.org http://lists.xml.resource.org/mailman/listinfo/xml2rfc

34. nroff, 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 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 www.1-4-5.net/~dmm/generic_draft.tar.gz

35. microsoft 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 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

36. LaTe  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/ www.cs.columbia.edu/IRT/software/l2x/

37. MIB Tools MIB reference and tools  O&M Web Site at www.ops.ietf.org/ www.ops.ietf.org/  http://www.ops.ietf.org/mib-review-tools.html http://www.ops.ietf.org/mib-review-tools.html  smilint at www.ibr.cs.tu-bs.de/projects/libsmi/www.ibr.cs.tu-bs.de/projects/libsmi/  SMICng at www.snmpinfo.com/www.snmpinfo.com/  MIB doctors at www.ops.ietf.org/mib-doctors.htmlwww.ops.ietf.org/mib-doctors.html

38. RFC End Game Once you think you are done there is a long way to go yet.  WG Last Call  IESG Review  Final Process

39. WG 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

40. IESG 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

41. Final 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

42. 48 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

43. Errata From: www.rfc-editor.org/errata.htmlwww.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.send email

44. Thank you Questions? edu-discuss@ietf.org avri@acm.org