Re: Object-Oriented Development and Documentation

Subject: Re: Object-Oriented Development and Documentation
From: "Wing, Michael J" <mjwing -at- INGR -dot- COM>
Date: Tue, 2 Jul 1996 08:50:30 -0500

Matthew and interested in COM documentation;

I, too, have found that many of my writing tasks are being replaced with
automation model analysis, reusable help, context-sensitivity, and so
forth. So much so, that I would guess that writing consumes only 20% of
my time. For example, the products that I document (I write
programmer's reference material) are created in applets. Applets are
reused between applications. For example, a 3d mechanical design
package and a cartographic package may both use the complete text
applet; however, one of the packages may only use a portion of the
geometry applet. This presents some logistic documentation problems as
follows:

1) Common topics must be generic to allow single-source text. For
example, the section of code containing common spatial geometry editing
(move, copy, delete) cannot have specific product references because the
topic may be reused in another application's documentation. Therefore,
I have to analyze the automation model to determine which topics are
generic and which are product-specific. The topics must then be tagged
so that they can be included/excluded in the application's help. I use
a common topic file (in Word format rather than RTF format to increase
field update speed) with bookmarks and the INCLUDETEXT field to allow a
single source for common text blocks. By using the INCLUDETEXT field, I
can vary the help topic's functioning (start-up macros; example
references, ALinks, and so forth) while using a single source for my
text.

2) Reusable topics. Because a COM application's construction can be
customized and added-to, the help must handle multi-configurations (and
versions) of the application. The document design is complicated when
an application only exposes a portion of the applet to the user. I use
build tags to differentiate between versions, usage, and variation. I
also use ALinks so that links that exist in one configuration are not
broken when not used in another configuration.

3) Multiple help file configurations. Context sensitivity is also an
area that must be designed carefully in COM documentation. A
typelibrary can only reference one help file; however, the typelibrary
may be used in many applications. Therefore, I have to determine the
largest family grouping of each area of automation functionality so that
it has an independent help file. I cannot make a help file for each
typelibrary because it may unnecessarily result in a hundred or more
help files. I create separate HPJ files (with appropriate build tag
inclusions) to compile applet help for applications that use the full
applet functionality and for applications that use partial applet
functionality. This supports the use of single-source topics.

The application help consists of a master (shell help file) which links
the TOCs and indici of the applet help files. I circumvent multiple
link listings (topic titles appearing more than once) while maintaining
a single-entry index by varying my Alink terms in similar topics but
maintaining consistent KLink terms. This methodology allows me to
quickly add applet functionality to an application's help (should
functionality be added or expanded) without much editing of the RTF
files (and producing a ripple effect on other help).

4) Object diagrams. The object hierarchy is the backbone of the
automation functionality and interlinking of functionalities. It is
also the backbone for my help design. Much digging into the automation
model is necessary to portray the object hierarchy. This is further
complicated when an object (such as Application) can assume multiple
objects. That is, if the object is a document and that document can be
a spreadsheet, word document, power-point slide, and so forth. I show
object hierarchies through hypergraphic object trees. The applicable
tree is automatically displayed when the user invokes an object topic.
The object tree only shows the paths leading into and out of the object
of interest. When branching is excessive or variable for an object, I
have used pop-up diagram, If-Then macros, and so forth to provide the
choices.

>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-



Previous by Author: Words that end in - GRY
Next by Author: Re: Fonts and other arguable issues
Previous by Thread: Object-Oriented Development and Documentation
Next by Thread: Re: Object-Oriented Development and Documentation


What this post helpful? Share it with friends and colleagues:


Sponsored Ads