Re: Suggestion for Sections in I-Ds(and RFC) containing MIb modules

["C. M. Heard" <heard@pobox.com>]

On Sun, 25 Sep 2005, David T. Perkins wrote:
> In the "Guidelines for MIB Documents", it doesn't say exactly
> what the sections should be in such documents. I'm reviewing
> two documents from a collection of 3. Each of them specifiy
> the sections differently. In particular, the sentence "The
> key words ... [2119]." is specified in different places.
> In the little bit of searching through documents telling
> people ho to write I-Ds (and RFCs), there were no explicit
> rules. (And such a reference was not even included in
> some guideline documents.) Thus, I suggest that the
> "Guidelines for MIB Documents", be a little more specific
> about its suggestions for sections.
> 
> Maybe all of this is done "automagically" by the XML-to-RFC
> tools.
> 
> I suggest that document have the following sections:
> 
> unnumbered "Status"
> unnumbered "Copyright"
> unnumbered "Abstract"
> unnumbered "Conventions"
> unnumbered "Table of Contents"
> Numbered "Introduction"
> Numbered "MIB boilerplate" (copied from 
>                       http://www.ops.ietf.org/mib-boilerplate.html)
> Numbered "Overview of Modules"
> Numbered "Relationship with Other MIB Modules"
> Numbered "MIB Module definition(s)"
> etc. (as specified in the "Guidelines for MIB documents")

The main reason why no such guideline exists in the current version
of the MIB review guidelines (RFC 4181) is because the authoritative
requirements documents -- http://www.ietf.org/ietf/1id-guidelines.txt
and http://www.ietf.org/ID-Checklist.html for Internet-Drafts, and
http://www.ietf.org/internet-drafts/draft-rfc-editor-rfc2223bis-08.txt
for RFCs -- require only that RFC 2119 be cited as a normative
reference if the relevant keywords are used, but don't require that
it be in any particular place.  It is common to have a section
entitled "conventions" for this purpose, but as you noticed it
appears in different places depending on the author's preference.
I do understand that xml2rfc puts it in a particular place but I am
not sure where that is.

One thing, however, that I'm fairly sure of is that every "conventions"
section I've ever seen in a published RFC appears after the table of
contents in what 2223bis calls the "body of the memo" and has a section
number.  We most certainly don't want the RFC editor moving this thing
around and adding a section number to satisfy their style guide, since
that would cause all subsequent sections to be renumbered with the
attendant problems on section cross-references.

> Ideally, there would be a "template" (or "skeleton") I-D
> for authors so they would not have to spend so much time
> working on details to make MIB I-Ds consistent. (Consistency
> is a VERY GOOD THING, since it helps to ensure that documents
> are complete, and that documents are easy to read.)

I agree with this.  I would also say, however, that if the location of
the "conventions" section is to be locked down, that it should appeat
in that place all I-Ds and RFCs, not just MIB documents.

//cmh