Re: thoughts on documentation reuse.

[Andy Bierman <abierman@cisco.com>]

At 01:45 PM 3/22/2002, Wes Hardaker wrote:

I'm always in favor of reducing the amount of work and text needed
to convey the semantics for a given piece of management information.
I also think it's important to keep the tool requirements to a
minimum level. If there was a freely available, properly maintained
tool for this purpose, then I wouldn't have any objections.

Another approach is to do a much better job organizing and
managing type definitions. If we kept H files as scattered
and unorganized as we do for TEXTUAL-CONVENTIONs, we would 
get fired from our jobs as programmers.  Sometimes we
let the standards process itself prevent us from following
good engineering practices, and cut-and-paste is used to
get around the problem. 

I would rather have properly organized TYPEDEFs than a tool
that did the cut-and-paste automatically. Maybe a combination
of both approaches can give everybody what they want.

Andy



>The other day I came up with an idea that I hated originally, but have
>grown to like it more as it has settled in my poor head.  The other
>day, I mentioned that we've clearly decided (I think) that we should
>optimize for the MIB readers and writers and not for the compilers.
>I'm pretty sure we've all agreed on this, but as I stated in the
>meeting, I'm not sure which of the "readers" and "writers" groups we
>should try and please the most.  
>
><aside>
>And, by the way, I wasn't trying to say that {}s were bad.  I
>was trying to say that un-needed structure like {}s, and ;s aren't
>useful to readers unless they provide a purpose.  {}s are good to
>people because they provide grouping, which is a very valid purpose.
>;s, however do nothing for the reader but add clutter to the screen.
>They already have a \n to make use of.  Only the compliers really need
>the ;s, and even this is questionable.
></aside>
>
>Anyway, the biggest problem that was talked about in the meeting was
>that reading OO like documentation is very difficult because of
>needing to follow the references.  But, cut-n-pasting 5 billion lines
>of text into every row-creation column is equally as bad.
>
>So, I'm now thinking we need not 1 but 2 MIB formats.  One which is
>short, allows reuse of documentation itself, and compiles into one
>which is more readable and with greater text auto-expansion.  This is
>already similar to hove IDs are published themselves, as no one writes
>straight text.  They write it in nroff, xml, word, latex, etc and have
>it produce the resulting text.  I'm beginning to think that a similar
>approach would be a good thing for MIBs.  And possibly both the
>compiled and the uncompiled versions should be published, but
>certainly the compiled version.  As an example, I'll try to take an
>example from Andy's lastest document:
>
>  VAR STRUCT myAddress {
>      SYNTAX      HostInetAddress
>      STATUS      current
>      DESCRIPTION
>          "Internet address of this host."
>  } ::= { someBase 1 }
>
>The problem is that if someone was truly confused by the syntax
>statement above, they'd have to look up  the resulting document
>describing a HostInetAddress.  The writer wants to simply state the
>above, however, because they don't want to provide a greater
>description because that takes time and energy to ensure that the
>multiple cut-n-paste results are accurate (over time).
>
>So, if HostInetAddress was define like (not that I'm not trying to
>make this concept look perfect in syntax, at this time, I'm just bring
>the idea forward itself.  The exact syntax is left for future
>consideration if the concept idea is appreciated):
>
>  TYPEDEF STRUCT HostInetAddress {
>      DESCRIPTION
>         "Internet address for an end-station host, adhering
>          to the SMIv2 'associated objects' design approach."
>
>-------------------------------------------------- new stuff here ----------
>      DESCRIPTIONTAG addressdescr       
>         "An internet address SYNTAX type is composed of a address
>          type and a representational UNION containing the value."
>-------------------------------------------------- end new stuff  ----------
>
>      SCALAR addrType {
>         SYNTAX      InetAddressType
>         MAX-ACCESS  read-only
>         STATUS      current
>         DESCRIPTION
>             "The type of Internet address."
>      } ::= 1
>
>      UNION addr {
>         SYNTAX      InetAddressUnion
>         STATUS      current
>         DESCRIPTION
>             "The Internet address."
>      } ::= 2
>  }
>
>Then myAddress, might be redefined as (looking kind of java-tagish in
>this example, with an @ in front of the key word):
>
>  VAR STRUCT myAddress {
>      SYNTAX      HostInetAddress
>      STATUS      current
>      DESCRIPTION
>          "Internet address of this host.
>
>           @magicalinclude addressdescr"
>  } ::= { someBase 1 }
>
>Thus, the above though ugly to readers would help writers reuse text
>without requiring massive cut-n-pasting and thus would increase the
>understand of what a given object was.  The writer->reader mib
>conversion would then compile the template mib to produce something like
>
>  VAR STRUCT myAddress {
>      SYNTAX      HostInetAddress
>      STATUS      current
>      DESCRIPTION
>          "Internet address of this host.
>
>           An internet address is composed of a address type and a
>           representational UNION containing the value."
>  } ::= { someBase 1 }
>
>Doing something like this would allow writers to include standard
>descriptions of parent mib objects with a simple "include" directive,
>but would allow it to be slightly more readable from the readers point
>of view if they haven't seen the parent object types before.
>
>I didn't really like this idea when I first thought about it, but the
>more I thought about it the more I realized that it would solve a
>number of problems.  It would have to be used carefully, of course,
>and included documentation strings should probably always be
>paragraphs in their own right rather words, pieces of sentences or
>sentences to be included into other paragraph or sentence constructs.
>
>I'd recommend that the fully compiled MIB be published and possibly
>that the "reduced" form be published in IDs as well since MIB authors
>would need to use any references defined within.  Yes I realize this
>increases the length of IDs (or at least appendix portions maybe).
>
>Thoughts?
>
>(Randy and I had a discussion about this and he mentioned "XML" and
>"style sheets" as the probably best way of accomplishing something
>like this in his mind)
>-- 
>Wes Hardaker
>NAI Labs
>Network Associates