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

From: "Adrian Farrel" <[email-masked]>
Date: Mon, 15 Jan 2007 18:38:28 -0000

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
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf

---

From: "Wijnen, Bert \(Bert\)" <[email-masked]>
Date: Fri, 19 Jan 2007 03:04:50 +0100

I am basically OK with this document.

Some comments you may consider though:

- Should you add aa [TODO] to section 5.1 which states that
  the editor of the document should describe the Textual
  Conventions (if any) in the MIB module?
- I wonder if guidance is needed that they can leave out sect
  5.1 if there are no TCs at all.
- in Sect 5.3, would it make sense to advise to also describe
  the tables (and their relationships to each other)?
  I think that such would be useful.
- In sect 5.3, it might be good to suggest that the editor 
  explains how congestion control is addressed for notifications
  (as per RFC2914)

Bert Wijnen

> -----Original Message-----
> From: The IESG [mailto:[email-masked]] 
> Sent: woensdag 10 januari 2007 7:40
> To: IETF-Announce
> Subject: Last Call: draft-harrington-text-mib-doc-template (A 
> Template for Documents Containing a MIB Module) to BCP 
> 
> The IESG has received a request from an individual submitter 
> to consider the following document:
> 
> - 'A Template for Documents Containing a MIB Module '
>    <draft-harrington-text-mib-doc-template-02.txt> as a BCP
> 
> The IESG plans to make a decision in the next few weeks, and 
> solicits final comments on this action.  Please send 
> substantive comments to the [email-masked] mailing lists by 
> 2007-02-07. Exceptionally, comments may be sent to 
> [email-masked] instead. In either case, please retain the 
> beginning of the Subject line to allow automated sorting.
> 
> Note that the document includes a Normative Reference to RFC 
> 2629 which is Informational. This is a Downward Reference as 
> per RFC 3967. 
> 
> The file can be obtained via
> http://www.ietf.org/internet-drafts/draft-harrington-text-mib-
> doc-template-02.txt
> 
> 
> IESG discussion can be tracked via
> https://datatracker.ietf.org/public/pidtracker.cgi?command=vie
> w_id&dTag=14807&rfc_flag=0
> 
> 
> IETF-Announce mailing list
> [email-masked]
> https://www1.ietf.org/mailman/listinfo/ietf-announce
>

---

From: Keith McCloghrie <[email-masked]>
Date: Fri, 19 Jan 2007 09:22:29 -0800 (PST)

> The IESG has received a request from an individual submitter to consider
> the following document:
> 
> The IESG plans to make a decision in the next few weeks, and solicits
> final comments on this action.  Please send substantive comments to the
> [email-masked] mailing lists by 2007-02-07. Exceptionally, 
> comments may be sent to [email-masked] instead. In either case, please 
> retain the beginning of the Subject line to allow automated sorting.

Here are some comments:

1. Is the title correct ??  That is, is this a document which applies
to "Documents" or does it only apply to I-Ds ??  (Note that checking
the Abstract doesn't answer this question, see example in #2 below.)

If this document applies to RFCs as well as I-Ds, then text is needed
to state that Appendix A and Appendix B apply only to documents which
are I-Ds.

It would also be helpful to be clear in advance whether this document
is intended as a guide to folks who are new to writing I-Ds containing
MIB modules, or as a rule book to be rigidly applied by the MIB Doctors.
The use of "Template" suggests the former, but it has many MUSTs. 

2. For beginners, I think this document is quite confusing, because of
the method it uses to include I-D boilerplate for two different
purposes: i) for itself as an I-D, and ii) in the template that it is
describing for other I-Ds/documents.  The document repeatedly tries to
use a single section for both purposes, and sometimes it fails and
that's what creates the confusion.  Here are two examples:

a) the Abstract says:

   This memo defines a portion of the Management Information Base (MIB)
   for use with network management protocols.  In particular it defines
   objects for managing [TODO].

   [TODO]: describe what functionality will be managed using this MIB
   module.  It can be good to mention the protocol being managed, and
   whether there is a particular aspect of the protocol to be managed,
   or a particular goal of the module.  But keep it brief.

none of this text is an Abstract for *this* I-D -- it applies only as
part of the template for use in other documents.

b) the "Note: Foreword to template users" says:

   [TODO]: please remove this Note prior to publication.

It's not clear which "publication" this is referring to.

So, I think it would be less confusing to re-organize this document
to have the template embedded inside it (not superimposed on it), such
that each boilerplate section is either: of this document, or within the
template, i.e., have no one boilerplate section used for both purposes.
For example, the template could have additional indentation as the means
for the reader to know which is which.

2. There are a couple of references to "SAMPLE-MIB" and the reader is
left to guess what that means.

3. Section 5.2 suggests having a "section for each subtree in the MIB
module".  The granularity of such sections is situation-dependent,
i.e., having sections on a per-subtree basis might be appropriate in
some cases, but there are many other cases where having sections on a
per-MIB-conformance-group basis is more appropriate.

4. Section 6.1 doesn't belong in a MIB document template:
 - saying "The SAMPLE-MIB does not duplicate those objects." needs to be
   true for all objects, not just the 'system' group -- it should also
   be true for all other MIBs, not just for some "SAMPLE-MIB".
 - if "does not duplicate" is a "Relationship", then all other MIBs in
   the world would need to be listed here, which is obviously impossible.
 - if someone feels strongly that this needs to be said, put it in (an
   update to) RFC 4181.
 - it's possible that some MIB modules will have a real "Relationship"
   with the 'system' group, and if so, then a modified version of this
   section would be needed, which is currently precluded because this
   section doesn't have a "[TODO]" marker.

5.  Section 8 says:

   o  [TODO] writeable MIB objects that could be especially disruptive
      if abused MUST be explicitly listed by name and the associated
      security risks MUST be spelled out; RFC 2669 has a very good
      example.

I agree that RFC 2669 is a good example, but not all "writeable MIB
objects ... [are] explicitly listed by name" in 2669.  In some cases,
2669 lists objects like this:

    ... manipulation of the docsDevNmAccessTable, docsDevFilterLLCTable,
    docsDevFilterIpTable and the elements of the docsDevCpe group may
    allow an end-user to ...

without explicitly listing all of the writeable MIB in those tables/that
group.  So, I suggest that these two:

   o  [TODO] writeable MIB objects that could be especially disruptive
      if abused MUST be explicitly listed by name and the associated
      security risks MUST be spelled out; RFC 2669 has a very good
      example.

   o  [TODO] list the writable tables and objects and state why they are
      sensitive.

should be clarified as alternatives, together with a third alternative
of listing objects contained in a group (as used in RFC 2669, see above).

Similarly, for readable objects, tables and groups.

6. Even when Appendix A and Appendix B are applicable, I suggest that
they don't need to be Appendix A and Appendix B.  For example, if the
I-D has other Appendicies, then the Change Log could be Appendix C.
Indeed, I now put the Change Log near the front of my I-Ds, rather than
as an Appendix, because I think that has some advantages, but I'm not
suggesting that you require everyone else to use my preference.

Keith.