[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Draft MIB Review Guidelines
>>>>> C M Heard writes:
Mike> Back in August, when I stirred up the controversy over whether
Mike> TCs should get to remove syntactic constraints of base types,
Mike> Bert Wijnen asked for a volunteer to write a CLR document. That
Mike> volunteer turned out to be me. The project ended up morphing
Mike> into a MIB review guidelines document, which turned out to be
Mike> quite a bit harder to organize that I thought it would be. I've
Mike> been struggling to get it written ever since.
Thanks for picking up this work. I believe such a document is highly
useful. Below are some nits, comments and suggestions.
1. In the Introduction:
"meet or exceed certain generally accepted standards of"
I suggest to remove "or exceed" since it is hard to measure
something that goes beyond what is generally accepted...
2. The RFC editor will love it if you cite standard numbers. So
instead of writing
"requirements of SMIv2 [RFC2578] ..."
you may want to write
"requirements of SMIv2, STD 58, [RFC2578] ..."
3. In section 3, you wrote that the narrative part MAY include a
section that briefly describes the structure of the MIB module. I
believe that this section SHOULD contain a description of the
structure of the MIB module in terms of the conceptual structure.
(as opposed to e.g. the OID tree which is rather unimportant for
the first time reader and tools can easily generate them.) In
fact, a good MIB should have an informal (information) model, see
also draft-irtf-nmrg-im-dm-02.txt. I have run several times into
documents with hundreds of pages of SMIv2 definition and basically
no high-level description upfront, which is I think unacceptable.
4. Should we not simply include the boilerplate texts in this
document? They do not change frequently and if they do, we have a
good reason to revise and extend this document. ;-)
5. Regarding copyright notices: It should be spelled out that the
DESCRIPTION clause of the MODULE-IDENTITY clause should refer to
the copyright statement in the RFC. Here is a template:
Copyright (C) The Internet Society (2002). This version of
this MIB module is part of RFC XXXX, see the RFC itself for
full legal notices."
7. Should we have more guidelines on how to choose a good module
name?
8. In section 4.5:
Thus, a draft version of a MIB module MUST contain just one
REVISION clause that covers all changes since the last published
version (if any).
While the text is OK, I think it could be made clearer by
inserting "new" just before REVISION.
9. Using Gauge in an INDEX clause seems strange to me.
10. Do we want to say something about *Index TCs? I mean something
like: If you have an Index which is likely to be used to refer to
a table, please consider to introduce a *Index TC and another
*IndexOrZero TC with the ranges ...
11. Similar to my comment 9, in section 4.6.1.3, I think that Gauge is
not a generally aquivalent to an Unsigned. The second paragraph in
this section is confusing for me.
12. Should we add guidelines for checking MIB module revisions? In
particular, I request people who break SMIv2 rules (which
sometimes makes sense after a cost/benefit analysis) that such
things are well documented and explained in an SMIv2 comment.
Perhaps it would also be good to point people explicitely to tools
such smidiff which can produce lists to check differences quickly.
13. Appendix A:
"review the actual technical for compliance"
should be
"review the actual technical content for compliance"
14. Appendix B:
You can simplify your smilint examples to the following:
smilint -l 6 -i namelen-32 <module>
15. Acknowledgements:
Instead of "XML guide" just write "guide" (I do not think that
is relevant how we formatted this unpublished guide).
/js
--
Juergen Schoenwaelder <http://www.informatik.uni-osnabrueck.de/schoenw/>