RE: thoughts on documentation reuse.

["Ayers, Mike" <Mike_Ayers@bmc.com>]

> -----Original Message-----
> From: Andy Bierman [mailto:abierman@cisco.com] 
> Sent: Monday, March 25, 2002 09:48 AM

> At 08:18 AM 3/25/2002, Ayers, Mike wrote:
> 
> >> From: Andy Bierman [mailto:abierman@cisco.com] 
> >> Sent: Saturday, March 23, 2002 04:58 PM

> This requires that you do all the prep work of extracting 
> MIBs from RFCs.
> I don't think this problem of finding types is very important. It's
> not the reason MIBs can be difficult to use.  Personally, I don't
> want types expanded at every use. If others want 14 pages of text
> inserted at every instance of a RowStatus object, that's fine 
> for them.

	I am now thoroughly confused.  Please specify the behavior that you
are seeking here.  If you want the description of a TC, and someone has
written a novel, you'll get a novel.  What are you looking for?

> >>  But if people really wanted
> >> a tool that expanded referenced types inline, it should be
> >> fairly easy to create such a tool. 
> >
> >        So easy that I wonder why we're having this discussion.
> 
> Agreed -- somebody who wants this tool can go create and maintain
> it for everyone.

<SNOBBERY>
	Anyone who wants one can easily hack out their own without needing
someone else to do it for them.
</SNOBBERY>

> I've seen many times in WG meetings (even my own!) where the group
> recognized that a TC or even MIB objects really belong in a
> different document, but are totally unwilling to delay their
> own work so that another group can take ownership of the problem, 
> revise their charter, publish an I-D, go through Last Calls,
> and finally the RFC Editor will publish something. It saves
> at least a year to just leave the misplaced definitions alone.
> 
> This is different than the ridiculous argument that if we just let
> SNMPv3 lie still long enough, vendors and operators will flock
> to it like it was undiscovered treasure.

	You've got me here.  However, I think that we need to press for the
creation of a new process.  IANA is for maintaining relatively trivial
updates, and I don't think TCs are quite that.  I'd prefer to see a process
that requires WG review, but takes only about 1-2 months to complete and
doesn't require charter work (go straight into Last Call?).  I think that
such a process could unclog a number of pipes (SNMP encryption algorithms
spring immediately to mind).  If such a thing is impossible, I think I could
be convinced to support the IANA thing.

> >> As we start using more complex TYPEDEFs instead of simple TCs,
> >> some changes may be needed:
> >> 
> >> 1) Versioning
> >
> >        This is not only unnecessary, it is an invitation to bad
> >engineering.  There is a simple versioning scheme in place 
> right now: if you
> >change the functionality, you have created a new TC, if you 
> enhance the
> >functionality (old and new software can interact fully 
> without using the new
> >stuff, but new and new will use it), then you may keep the 
> name the same.
> >This is based on the fact that the only thing that matters 
> in the field is
> >whether or not older and newer implementations can 
> interoperate.  All else
> >is fluff.
> 
> So I change the name of FooType to BarType if it changes.
> This is remarkably similar to changing FooTypeV1 to FooTypeV2
> except the user has a clue what happened. This issue doesn't
> exist with TCs today, because they are only for base types,
> and only trivial changes are allowed.  If I add a new field
> to a struct, then how does a user of the BAR-MIB tell which
> version of FooType is actually used?  I would rather be
> able to change a struct if needed.  I would rather not
> have versioning either, but given the history of protecting
> people from their own mistakes, I don't know if this will be accepted.

	All of which changes nothing.  Either the change breaks
interoperability or it doesn't.  A few simple principles apply:

	(1)  The existing implementations must not need to know that a
change has occurred.  It must work with new implementations exactly as if
they were old implementations.

	(2)  The new implementations must be able to trivially detect
whether it is working with an old or new implementation, and should never
attempt to use new features on an old implementation.

	(3)  BONUS:  New features should be designed such that if they are
inadvertently used on an old implementation, the old implementation is
unharmed.

	If you violate (1), you have broken your implementations.  If you
violate (2), you are begging for trouble.  How does versioning, whether of
structs or TCs or whatever, change any of this?

> We don't have the ability to move a TC once it's already been defined
> in a MIB.  MIB tools don't handle this well at all, like OwnerString
> in RMON-MIB and then in IF-MIB as well. Maybe it's just bad tools.

	No.  It's the other edge of the sword that allows us to find the
definitions so easily.  Compare this to C code, where definitions can be
moved around header files trivially, and locating them therefore becomes so
difficult (unless the strictest of programming discipline is followed) that
my preferred tools for this are debuggers and full build tree grep.  Of the
two methods, I prefer the backpointer that we have now.


/|/|ike