Subject: Re: snmpconf comments should never include technical descriptions

From: "David T. Perkins" <[email-masked]>
Date: Tue, 13 Mar 2001 13:09:39 -0800

HI,

once again...

>Date: Tue, 13 Mar 2001 10:54:46 -0800
>To: [email-masked]
>From: "David T. Perkins" <[email-masked]>
>Subject: Re: snmpconf comments should never include technical
>  descriptions 
>In-Reply-To: <[email-masked]
> >
>References: <Your message of 09 Mar 2001 14:05:04 -0800. <[email-masked]>
>Mime-Version: 1.0
>Content-Type: text/plain; charset="us-ascii"
>
>HI,
>
>One approach that I use is to use the DESCRIPTION clause of the
>MODULE-IDENTITY construct to describe the MIB module and list
>abbreviations that the MIB module reader would find useful.
>The text to put in the RFC before a MIB module is background
>and explanations. It is for the reader that has not yet read
>the MIB module. The content of the MIB module is really a
>reference for people that have already read the document (RFC),
>and assumes that the background concepts are understood.
>That is, all the text in an RFC before a MIB module MUST not
>be moved to the DESCRIPTION clause of the MODULE-IDENTITY!
>
>Regards,
>/david t. perkins
>
>At 10:22 AM 3/13/2001 -0500, Jon Saperia wrote:
>>Wes
>>> 
>>> Ok, this is, then, a separate message on the subject.
>>
>>>From what you wrote below, I think we are in essential agreement and
>>Mike and Wayne and I can include text that carries your suggestion in
>>what I hope will be the final revision after the IETF.  One other item
>>that should be added though is that there is value in the front matter
>>of both standard and vendor specific MIB Modules that gives general
>>contextual or technology grounding for the MIB Module. I do not think
>>this violates your rules about putting things in the DESCRIPTION clause
>>though.
>>
>>thanks
>>/jon
>>> 
>>> IMHO, it is very bad practice to describe how an object or group of
>>> objects is supposed to behave, why it is in existence, etc, outside of
>>> the description clause for that object or group of objects.  Comments,
>>> specifically, should never be used to document an object in any way.
>>> Something like:
>>> 
>>> 
>>> 
>>> Proper and Improper use of MIB comments
>>> 
>>>   Comments within MIBs are started with two '-' symbols: "--".
>>>   Comments are ignored by any tools which systematically parse a MIB
>>>   definition in order to extract some set of information from it.
>>>   Because of this, it is extremely important that comments not be used
>>>   to describe how an object or group of objects is supposed to behave,
>>>   why they exist.  More generally, comments should not be used as a
>>>   form of documentation.  The proper place for documentation is in the
>>>   DESCRIPTION clause of an appropriate object.
>>> 
>>>   Comments are not without merit, however.  They can be used to
>>>   provide a separator between large sections of the mib, such as:
>>> 
>>>     --
>>>     -- Begin Acme notification objects
>>>     --
>>> 
>>>   They can also provide a place for MIB authors to comment on sections
>>>   that need to be fixed, or to document problems with an object.
>>>   Typically, though, these types of comments would be removed before
>>>   external publication.
>>> 
>>>   In short, if you're unsure of where to put text, put it in a
>>>   description clause not in a comment.
>>> 
>>
>>> 
>>
>>Thanks,
>>/jon
>>--
>>
>>Jon Saperia                  [email-masked]
>>                             Phone: 617-744-1079
>>                             Fax:   617-249-0874
>>                             http://www.jdscons.com/

---

From: Wes Hardaker <[email-masked]>
Date: 14 Mar 2001 07:11:34 -0800

>>>>> On Tue, 13 Mar 2001 13:09:39 -0800, "David T. Perkins" <[email-masked]> said:

>> be moved to the DESCRIPTION clause of the MODULE-IDENTITY!

David, I wasn't trying to imply that no text what so ever should go in
the RFC.  Some things, like background information, makes sense.  Some
things do not.

I don't remember the exact example, but one of the MIBS from the main
SNMPv3 RFCs (2570-2575) has (had?) the usage for the table in the
elements of procedure section above and the description clause for the
table didn't indicate how the data was to be used.  If I get the
chance, I'll go look through it again, but its a lot of text to
re-read :-)
-- 
Wes Hardaker
NAI Labs
Network Associates

---

From: Jon Saperia <[email-masked]>
Date: Thu, 15 Mar 2001 09:23:38 -0500

I think we have general agreement about what belongs in a DESCRIPTION
clause, and the types of text that belong in the front portion of a MIB
document.  What we do not have yet are a one or two concise sentences
for these guidelines. 

Wayne/Mike or others, would you like to propose a sentence or two?

Thanks,
/jon
--

---

From: Wes Hardaker <[email-masked]>
Date: 16 Mar 2001 08:34:29 -0800

>>>>> On Thu, 15 Mar 2001 09:23:38 -0500, Jon Saperia <[email-masked]> said:

Jon> What we do not have yet are a one or two concise sentences for
Jon> these guidelines.

One of my messages contained a template that should have been close,
but it was designed to be more of a section rather than a sentence or two.

-- 
Wes Hardaker
NAI Labs
Network Associates