Re: Last Call: draft-harrington-text-mib-doc-template (A Template for Documents Containing a MIB Module) to BCP

["Adrian Farrel" <adrian at olddog.co.uk>]

Hi David,

Thanks for taking on the drudge work to make something useful and
beneficial.

Comments below.

Adrian

===

Abstract

I think it would be useful if the abstract of this I-D was the abstract
*for* this I-D. That means that you should move the template abstract into
its own section.

===

Foreword to template users.

Ditto. That is, could this foreword become a real part of the I-D, pushing
the template text into its own section?

===
s/numerouse/numerous/
===
Foreword to template users.

Should the reference to RFC2223(bis) be a citation with an entry in the 
references section?

===
s/conclusive/complete/ ?
===
Foreword to template users.

Would be useful to include a note about the use of 'SAMPLE-MIB' in the 
template.

===

Section 1

The Introduction shown here is pretty skimpy. In fact, the Abstract has more 
text :-(
Can we make some recommendations about what to include here?

Citations of protocol specs, architectures, and protocol-specific management 
requirements?
References to other, related MIB modules?
Overview of why a MIB module is appropriate for this protocol and how the 
module is to be used?
Highlights of anything 'different' about the module? For example, read-only.

===

Section 2

Would it be helpful to highlight which sections are boilerplate and which 
are open for author-modification?

===

Section 5.1

Perhaps helpful to provide a [TO DO] to say what should be here.
For example,
  [TODO] describe the textual conventions defined in the MIB
  module, and their purpose.
  [TO DO] it may be helpful to highlight any textual conventions
  imported from partner documents.
(The latter, notwithstanding section 6)
===

Section 6

It is not clear that...
  Some management objects defined in other MIB modules are applicable
  to an entity implementing this MIB.  In particular, it is assumed
  that an entity implementing the SAMPLE-MIB module will also implement
  the 'system' group of the SNMPv2-MIB [RFC3418] and the 'interfaces'
  group of the IF-MIB [RFC2863].
...is example text rather than required text.

===
s/MIb/MIB/
===
Section 12.

Many, but not all, of these references are template. Some are specific to 
this I-D. Confusing?

===

Missing?

- Worked example. Maybe not mandatory, but
  very useful.
- Discussion of the use of rowPointer. Again, not
  mandatory, but can be helpful to readers.
  Cf. RFC3812 section 10.





_______________________________________________
Ietf mailing list
Ietf at ietf.org
https://www1.ietf.org/mailman/listinfo/ietf