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

1
IETF68 Mini-BOFMIB-Doctor-SponsoredMIB Document
Templates

• David Harrington

2
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

3
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

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 dont do MIB security considerations

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

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

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 ltincludegt your finished MIB into the
  document when ready

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

9
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_at_ietf.org
• https//www.ietf.org/mailman/listinfo/ops-area

10
Thank You

• Questions?
• Contact
• David Harrington
• ietfdbh_at_comcast.net
• dharrington_at_huawei.com