Re: thoughts on documentation reuse.

[Wes Hardaker <wes@hardakers.net>]

>>>>> On Mon, 25 Mar 2002 16:42:17 +0100, "Wijnen, Bert (Bert)" <bwijnen@lucent.com> said:

Bert> Then why is the @magicalinclude below needed at all?
Bert> Can just add the DESCRIPTIONTAG if it is a fixed tag, no?
Bert> I understand it is a bit less flexible... but I am not sure we
Bert> need another generic "include text" feature.

My (unexplained) thinking is that people write text in two ways:

1) a document which defines the object itself and is intended to be
   very full and explanatory, but wouldn't look good at all if it was
   cut-n-pasted directly into another document.

2) A string which is known to be "exported" is likely to be cleaner
   and be a better summary.

I thought about importing the entire DESCRIPTION clause itself, but it
just seemed that if the original author didn't realize that his text
might be used somewhere else would likely not write it in a fashion
that would be well written for somewhere else.

Also, it's likely I wouldn't ever want to import the entire
DESCRIPTION clause of, say, a RowStatus TC (to pick one at random ;-).
It's more likely that I'd want to incorporate only a "summary" of it.
IE, something that gives at least a notion of what it means to be a
RowStatus TC column, but not the entire legal definition.  I'd want to
repeatedly say "Don't forget, it's illegal to speed" but not "In areas
of suburban streets, it is illegal to travel at velocities greater
than 40 kph.  On streets composed of at least 4 lanes and bordered by
only commercial properties, it is illegal to travel at velocities greater
than 60 kph. ..."

Bert> I can tell you, if we had this for some of the RowStatus and StorageType
Bert> TCs, then we could have text inthere that explains what sort of stuff
Bert> these people MUST specify in their DESCRIPTION clauses and which they 
Bert> now often forget.

Think about the following usage:

In the RowStatus TC now:

            It is the responsibility of the DESCRIPTION clause of the
            status column to indicate under what circumstances the
            status column should be taken out of service (e.g., in
            order for the value of some other column of the same
            conceptual row to be modified).

In the RowStatus TC of the future:

      [the same sentence plus some magical pre-defined key words:]

       DESCRIPTIONTAG noCircumstances       
          "Rows may be modified without first setting the row to
          not-in-service."
       DESCRIPTIONTAG alwaysNotInService
          "Rows MUST be placed into not-in-service before any column
          is allowed to be modified."

Which would make writing a document of billions of RowStatus objects a
bit easier (plus if the text was cleaned up, it would affect all of
the resulting objects at once [at text-compile time at least]).  I
know my current MIB project with 23 rowstatus columns in it suffers
from not enough descriptions because my poor fingers just got too
tired to keep going.

-- 
Wes Hardaker
NAI Labs
Network Associates