IETF68 Mini-BOF MIB-Doctor-Sponsored MIB Document Templates David Harrington

IETF68 MIB Document Template MIB Doctors Purpose of MIB Doctors To educate authors to improve MIB documents To act as technical advisors to help design MIBs To provide “expert review” of MIB documents MIB Doctor expert review required Started in mid-90s MIB documents had inconsistent quality IESG Retreat, Jan 06 Focused on improving IESG performance MIB Doctor expert review process can take months Few MIB Doctors available (~10 active volunteers) Very detailed reviews required MIB documents from all areas of the IETF 22 November 2018 IETF68 MIB Document Template

IETF68 MIB Document Template Crappy Little Rules Concerns of NM Community with CLRs “crappy little rules”/”clarifying language rules” Hard for MIB writers to know all the rules Different MIB Doctors identify different issues MIB Review Guidelines created (RFC4181) To capture all the crappy little rules To reach MIB Doctor consensus on the rules Tools to help automate the checking process WGs review their docs before the MIB Doctors RFC4181 has improved quality and review times 22 November 2018 IETF68 MIB Document Template

What Causes Long Review Times? Problems with document quality Often poor formatting unintelligible content and grammar problems Specs are not clear and unambiguous References point to out-of-date RFCs and I-Ds Problems with MIB document consistency Authors order drafts in different ways Hard for Doctors to check for expected discussions Frequent problems with boilerplates MIB authors use old MIB modules as template Authors embed boilerplates in other sections Authors make minor, but important, changes Authors don’t do MIB security considerations 22 November 2018 IETF68 MIB Document Template

What Causes Long Review Times? Doctors must understand what is modeled MIB modules from all areas of the IETF Doctors do not know all emerging technology in the IETF MIB Doctors need to understand what is being managed to understand if it has been modeled well, and if the MIB “database schema” is well-designed Problems with MIB document clarity concepts of the managed protocol management requirements of the protocol how the MIB module relates to other MIB modules the purpose of objects in the MIB module 22 November 2018 IETF68 MIB Document Template

How to Reduce Review Times? Templates for authors Ensure templates have up-to-date boilerplates Describe desired sections, and what belongs in each section Authors are NOT REQUIRED to use templates Using templates should speed the review/approval process Improve consistency of reviews MIB Doctor consensus on the sections/order of the template MIB Doctor consensus on the advice included in the template MIB Doctors are NOT REQUIRED to use templates Improve automation of MIB document reviews Document can be manually diff’d against current template to check boilerplates are present and have not been altered Tools team can provide new tools to automate checking MIB document boilerplates, references, required sections, etc. 22 November 2018 IETF68 MIB Document Template

What Does the Template NOT Do? This template is for writing the document that contains a MIB module It is NOT for writing the MIB itself Other tools and templates are available for writing MIB modules Different MIB writers like different tools So, just <include> your finished MIB into the document when ready 22 November 2018 IETF68 MIB Document Template

IETF68 MIB Document Template Long Term Goals Improve quality of MIB documents Improve consistency and content of MIB modules by providing template guidelines for consideration of operability and manageability Improve automation of MIB Doctor reviews Improve speed of IESG approvals Translate MIB document templates and operations and manageability guidelines into templates for other NM data model documents (e.g., XML schemas for network management) 22 November 2018 IETF68 MIB Document Template

IETF68 MIB Document Template Short Term Goals Want reviewers Want authors to use the templates Want feedback and additional suggestions Templates, in both text format and XML2RFC format, are available at http://ops.ietf.org Updates to both are being worked on Discussion on ops-area@ietf.org https://www.ietf.org/mailman/listinfo/ops-area 22 November 2018 IETF68 MIB Document Template

IETF68 MIB Document Template Thank You Questions? Contact David Harrington ietfdbh@comcast.net dharrington@huawei.com 22 November 2018 IETF68 MIB Document Template