Re: Object-oriented Programming (OOP) Terminolgy in Documentation

["Less is more." <yvonne -at- VENUS -dot- SMARTSTAR -dot- COM>]

Harold Henke <hessian -at- VNET -dot- IBM -dot- COM> asks about OOP terminology in documents:

>I am in the process of writing a short article, more likely an
>"Opinion" piece for a software magazine on the use of OOP terminology
>in software documentation.

> If you have documented an OOP application, I would like to hear about your
experiences, such as: whether you used OOP terms,

We produce an application development environment for multiple platforms.
The product allows users to create applications by creating object instances,
setting their attributes, and using their methods.

We use OOP terminology throughout our documentation. We do explain the OOP
terminology and give examples, because it is new to some part of our audience.
Also, different companies mean different things when they say their product is
"object-oriented". It's a marketing buzzword, which means marketing people use
it without knowing what they are talking about.

> if so, for what audience,

Our audience is made up of application developers, who in most cases are
programmers. They are not necessarily familiar with OOP terms, since many of
them have been developing applications since the old COBOL days. Companies buy
our software to save them time, so I don't assume that the audience has the
same level of OOP sophistication that our developers do. However, some of them
are very knowledgeable about OOP, so I don't try to claim more capability than
we have.

> and any other gems you might want to share with the software development
> community.

If your users don't need OOP terminology to understand the product, I'd
recommend against using it. The printer is a good example. People already
understand sending something to a printer. Just because it is internally
implemented as an object, doesn't mean you have to talk about it that way.
(Reminds me of a former manager who wanted the manuals to explain just how
difficult it was for us to write the wonderful software we were selling -- how
many lines of code, etc.)

Use OOP terms when they are relevant to understanding the software. For
example, our script language uses "objectpaths" to address attributes and
methods of objects (window_name.object_parent.object_child.attribute).
If we didn't use OOP terminology, we couldn't explain this syntax.

One thing I've found to be important when documenting a class library is to be
clear about which attributes and methods apply to each class. Often,
documentation for class libraries says that a class has "this set of
attributes, plus all the attributes it inherits from this other class". The
other class inherits attributes from its parent class, and so on. The poor
user has to trace back the inheritance tree to get a full list of attributes.
And, sometimes a class inherits an attribute that is technically available, but
isn't really useful. Documentation should provide the true list for each class.

Another issue is that we generate printed and online documents (and parts of
the software) for our product from a database. We've found OO software to be
especially well suited for database publishing techniques. We have relational
tables for "class", "attribute", "method", "class_attr relation", and
"class_method relation".

Yvonne DeGraw
Sr. Technical Writer
SmartStar Corporation
yvonne -at- smartstar -dot- com