Re: thoughts on documentation reuse.

[Andy Bierman <abierman@cisco.com>]

At 09:44 AM 3/23/2002, Wes Hardaker wrote:
>>>>>> On Fri, 22 Mar 2002 18:20:49 -0800, Andy Bierman <abierman@cisco.com> said:
>
>Andy> I also think it's important to keep the tool requirements to a
>Andy> minimum level. If there was a freely available, properly
>Andy> maintained tool for this purpose, then I wouldn't have any
>Andy> objections.
>
>I was coming at it from the impression that someone from the working
>group would produce a reference tool.


are you volunteering? :-)


>Andy> Another approach is to do a much better job organizing and
>Andy> managing type definitions. If we kept H files as scattered
>Andy> and unorganized as we do for TEXTUAL-CONVENTIONs, we would 
>Andy> get fired from our jobs as programmers.
>
>heh
>
>Andy> I would rather have properly organized TYPEDEFs than a tool that
>Andy> did the cut-and-paste automatically.
>
>The problem frequently brought up in the meeting was that people
>(readers) simply didn't want to follow references.  They wanted as
>much descriptive information as possible in one place.
>MIB-knowledgeable people probably would read the shortened
>pre-compiled version instead since they don't want to page down
>through all the repeated lines of text.  It optimizes for both cats
>and dogs, which is what I was trying to get at.

They already have to follow references for TCs.
I think the problem is that it's not very clear where they
should look for the TC definitions.  I like having the local
TCs defined at the top of the MIB, and not cut-and-pasted
for every object instance in the MIB.  But if people really wanted
a tool that expanded referenced types inline, it should be
fairly easy to create such a tool. 

We need to rethink our TC procedures as they become TYPEDEFs.
Steve Waldbusser suggested in the RMONMIB WG meeting that maybe
IANA should maintain common TC modules.  I think this idea
is worth investigating. If there were well-defined modules
based on functionality (like stdlib, string, time, inetaddr, etc.)
that could be modified without waiting a year to get an RFC out,
then people would be more willing to use them.

As we start using more complex TYPEDEFs instead of simple TCs,
some changes may be needed:

1) Versioning
   TYPEDEFs may need a version field embedded in the name,
   or perhaps identified in a VERSION or LAST-UPDATED clause for the type.
   FooTypeV0 would represent a type in a work-in-progress.
   FooTypeV1 would be the initial version of the type.
   If the type is changed or extended over time, FooTypeV2, etc.,
   would be published (and FooTypeV1 deprecated). Many times
   the user doesn't care, so FooType would refer to the most recent
   version of the type.  MODULE-COMPLIANCE info may need to be added
   to identify the exact version used in a particular MIB version.

2) Relocation
   It's not always easy to recognize that a TYPEDEF is defined in the
   wrong place (e.g., RMON OwnerString).  It might be useful to have
   a RELOCATED clause in the TYPEDEF, to let humans and machines
   know the FooType in the FOO-MIB is the same FooType in a IANA
   common type module.


>Andy> Maybe a combination of both approaches can give everybody what
>Andy> they want.
>
>Probably.
>
>-- 
>Wes Hardaker
>NAI Labs
>Network Associates 

Andy