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

2. 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

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

4. 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

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

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

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

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

9. 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
Updates to both are being worked on
Discussion on
22 November 2018
IETF68 MIB Document Template

10. IETF68 MIB Document Template
Thank You
Questions?
Contact
David Harrington
22 November 2018
IETF68 MIB Document Template