Re: Documenting Object Oriented Applications

["Wing, Michael J" <mjwing -at- INGR -dot- COM>]

>----------
>From:  Shmuel Ben-Artzi[SMTP:sba -at- NETMEDIA -dot- NET -dot- IL]
>Sent:  Friday, July 26, 1996 6:04 PM
>To:    Multiple recipients of list TECHWR-L
>Subject:       Re: Documenting Object Oriented Applications

>Mike,

>I understand the principles of OOP from an applications development
>point of
>view, but your comprehensive analysis of the documentation procedure is
>quite instructive. If I understand you correctly, only
>context-sensitive
>online (help-type) documentation can provide the degree of portability
>and
>adaptabiliy necessary to properly document an OO application, correct?

I didn't mean to imply that this was the only method.  I think on-line
provides much more flexibility to O-O than does printed, but printed is
not precluded.  In fact my first experience with this type of printed
documentation was before O-O.  I was writing a manual for a Timing
Signal Generator.  This telecommunications device was modular.  The user
could buy it in one of a many configurations (buy choosing the modules).
 This provided a dilemma on how write a manual that supported modularity
but did not require duplicate word processor files.

To solve this problem, I split the manual into three sections.  The
first section was for the generic unit.  Even though the instrument
could contain a wide variety of components, the components fit into a
five functional categories.  There was an signal input, a computerized
analyzer, a local frequency source, a signal converter, and an signal
output section.

Regardless of whether the local frequency source was a quartz oscillator
or a rubidium standard or the frequency/wave shape of the output, there
was enough common functionality to document.  The common workings of
each functional area (such as the input signal), the relationship
between functional areas, external connections, installation, start-up
procedures, and other information that was independent of module
specifics was in this manual section.

The second part was the software commands.  This section was
customizable.  Therefore, I would keep individual written chapters for
each version of the software.  The manual received the software chapter
that was applicable to their instrument.

The third part was the individual components.  I grouped the components
by function (input, local oscillator, and so forth).  Each component was
a stand-alone document (usually about 5 pages).  I had a document for
each component we manufactured.  To construct the manual I would look at
the customer's instrument configuration.  The manual would consist of
the generic first part, the software chapter applicable to version the
ordered, and the individual component chapters (grouped by function) for
only the modules in their configuration.  Therefore, when they ordered a
new module (such as another type of output signal board), the module
documentation went with it.  The customer just inserted (ring binders at
that time) into the appropriate section.

>And would this be true whether writing for the developer or for the end
>user?
>How about tutorials and collateral documentation?

Written documentation can be done in modules.  IMO, the modules can tie
together through an umbrella document.  While the modular documentation
is not application-specific, the umbrella document can be.  The intent
is to keep the umbrella document terse but providing smooth and logical
flow and connectivity between the modules.  If a variation of the
package exists, just create a separate umbrella document.  If an O-O
applet is changed, send a new module chapter (this is one place where
on-line scores a big advantage over written).

>Can you recommend a good reference volume on the design and creation of
>context-sensitive documentation?

I'm sorry, I can't.  I'm sure some exist but I've been using my own
methodology and it mutates frequently.

>Thanks and Shalom,

>Shmuel Ben-Artzi

Mike Wing

_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
_/
_/   Michael Wing
_/   Principal Technical Writer
_/   Jupiter Customization and Educational Services
_/   Intergraph Corporation
_/   730-7250
_/   mjwing -at- ingr -dot- com
_/

                  TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send administrative commands
         ALL other questions or problems concerning the list
       should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-