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

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

On Mon, 26 Sep 2005, David T. Perkins wrote:
> While the actual location of RFC 2119 language is not at all
> important, and the exact details of other "required" items
> are not so important, spending time on determining this
> and other things isn't worth the time of reviewers. There
> is a simple little script that checks to make sure that
> some boilerplate text is unmodified. I'm thankful that such
> a script exists, since it is better done with a script
> than a human.
> 
> The observation that I was making is that there are many
> little I-D (and RFC) rules that a reviewer is suppose
> to check. This is both a burden on the document writer
> and the reviwer. I just wish that for both writers and
> reviewers that this was "just taken care of".

I agree with all of this.  One of my least favorite tasks
when reviewing MIB documents is taking care of the stuff
that goes under the heading of "General Documentation
Guidelines" in RFC 4181.  The amount of time that I have
to spend on any review is finite;  and all of the time
that I spend worrying about stuff like whether the copyrights
notices are in order, whether all the boilerplate is included,
and whether the RFC 2119 imperatives are listed and that
document is included as a normative reference is time that
I will not be able to spend looking at the MIB module, which
after all is the main point of a MIB Doctor review.

> The other observation was that when there is "creativity"
> that is allowed in these boiler plate parts, as a reader
> of multiple documents (especially a collection from the
> same WG that is produced at the same time), you notice the
> differences and wonder if there was a reason
> for the differences. This is wasted time. I don't like
> people to waste my time, and I bet others don't like
> wasted time either. 
> 
> So my primary suggestion is that a MIB document skeleton
> be created so that document authors (and reviewers)
> don't need to spend any time on this aspect of documents.
> I believe that the suggested organization of sections
> found in the MIB reviewers guidelines doesn't go far enough.

I find all of this hard to argue with.

> To create such a skeleton, someone needs to decide what
> is in it, and how it is organized. I don't care about
> things like where the RFC 2119 language is included.
> There are many other things I passionately care about,
> such as I included in recent email to this list about
> what should be included
> in the DESCRIPTION clauses for tables and rows.

Here is what would propose for such a skeleton:

unnumbered first-page header (as specified in 1id-guidelines)
unnumbered "Status of This Memo" (as specified in 1id-guidelines)
unnumbered "Copyright Notice" (optional for drafts, but include in template)
unnumbered "Abstract" (as specified in 1id-guidelines and rfc2223bis)
unnumbered "Table of Contents" (required for documents over 15 pages)
numbered "The Internet-Standard Management Framework" (MIB boilerplate)
numbered "Conventions" (RFC 2119 stuff, add NOT RECOMMENDED to list)
numbered "Overview" (as in the MIB review guidelines)
numbered "Definitions" (as in the MIB review guidelines)
numbered "Security Considerations" (as in the MIB review guidelines)
numbered "IANA Considerations" (as in the MIB review guidelines)
optionally, numbered "Acknowledgments" and/or "Contributors" sections
optionally, appendices with appendix labels rather than section numbers
unnumbered "References" (as in the MIB review guidelines)
unnumbered "Author's Address" or "Editor's Address"
unnumbered IPR Boilerplate (full copyright notice & intellectual property)

Note that the section ordering and the rules about what gets
numbered and what does not are intended to be consistent with
current RFC Editor practice.  That will ensure that section numbers
(and section number references) don't change when the document is
published.

Now, the best way to make this happen, in my view, is not to make up
another batch of CLRs for us to enforce (that will increase reviewer
workload, I think, rather than decrease it), but rather to dress up
the tools to encourage people to do this.  So I think Juergen's
suggestion to add this capability to xml2rfc is the right way to go.
Any volunteers?

//cmh