Re: Documenting Object Oriented Applications

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

>----------
>From:  Gem Smith[SMTP:gemsmith -at- ELECTROTEX -dot- COM]
>Sent:  Thursday, July 18, 1996 10:01 AM
>To:    Multiple recipients of list TECHWR-L
>Subject:       Documenting Object Oriented Applications

>Hi Ya'll -

>I'm new to this list and have been enjoying the conversation and the
>wit.

>I am a contract writer and have had conversations with two potential
>clients both of whom wanted to know if I had ever documented an object
>oriented application before. I had to answer "no".

>My question is how is writing for an OOA different? When I worked in a
>corporate environment, I wrote software user manuals and from the
>little
>these folks have told me, I deduce that that is what they need.

>Thanks in advance for your help.

>Gem

A major difference that I have found in documenting O-O applications is
reusability.  In the past, an application requiring graphic editing,
text editing, tables, and so forth would contain it's own code for these
functions.  However, with O-O, a piece of functionality (often referred
to as an applet) can be reused in several applications.  Therefore, a
single text applet can be used for a word processor, spread sheet, a 2-D
drawing package, and so forth.

In an O-O application, the available commands depend on the active
object.  If a block of text is selected, the commands furnished through
the text applet are available.  Select a line and the 2-D drawing
package commands are available.  With an O-O based application,
functionality can be upgraded and extended without upgrading the entire
application.  For example, if an improved text applet is available, just
replace the text applet.

Reusable functionality creates a need for documentation that is not
application-specific.  Therefore, the documentation on using the text
edit commands cannot reference specific products, menus, dialog boxes
(unless indigenous to the applet), or functionality outside of itself.
This modularity affects on-line documents to a greater degree,
especially if context-sensitivity is involved.

The applet addresses only one help file.  If the help for that applet is
part of an entire application's help, the help for an individual applet
cannot travel with the applet to another application (it contains
non-applicable information).  Therefore, the construction of the online
documentation needs to reflect the design of the O-O application.

Other O-O documentation involves programming references.  Usually this
documentation is for the Application Programming Interfaces (APIs).  At
one level, is the C++ source code.  This documentation describes
function calls, objects, events, and so forth used in processing such as
relationships, membassy, rendering, and so forth.  Mostly this
documentation is internal and is used by programmers who are building on
an O-O application's core technology (although it may be used by 3rd
parties who have bought the technology to develop their own extensions).

The other level of O-O programming documentation is the exposed
automation.  This documentation provides syntax, examples, object
hierarchy, and so forth for the functionality exposed to the user.
Typically, but not exclusively, automation is handled through Visual
Basic.  Automation allows the user to write customized functions,
wizards, dialog boxes, and so forth.  For example, the user of a 3-D
drawing package could write an automated wizard that presents a GUI for
a screw.  The user then provides the parameters (thread depth, point
type, taper, and so forth) via the GUI and the automation script draws
the screw using those parameters (instead of the user drawing the screw
details).

Furthermore, on-line documentation for O-O automation involves
context-sensitivity for the automation programming environment.  The
context sensitivity allows programmers to press F1 with the cursor in
the code window, and display the help topic for the automation element
(object, method, property, event, and constant) at the current position.
 The context sensitivity also allows the applicable display help topic
for an element selected in the object browser.  Getting the on-line
document to interlace help for a combination of applets while providing
context-sensitivity independently to the applets takes a good deal of
design in the document.

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-