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

Subject: Re: Object-oriented Programming (OOP) Terminology in Documentation
From: "Susan W. Gallagher" <sgallagher -at- STARBASECORP -dot- COM>
Date: Mon, 16 Jan 1995 16:06:27 -0800

The question from Harold was:


> And I would like to offer you all a moment in the sun as I am looking
> for a few good quotes. If you have documented an OOP application, I would like
> to hear about your experiences, such as: whether you used OOP terms, if so,
> for what audience, and any other gems you might want to share with the
> software development community. (If I choose your quote, I will send you a
> note asking your permission to use your name and company in the article."

In documenting an oo application development system based on Smalltalk
I stuck with industry standard terminology. Our audience analysis
indicated some expertise in OO-land, but most of the audience was
coming from the wonderful world of COBOL. We were very careful to
explain our terms and eventually provided a Smalltalk primer. However,
I only used OO terms to describe actions in OO programming that they
had to perform (e.g., create an object, subclass a method, etc.). I
did not use OO terms to explain the way the program ran. It didn't
seem necessary.

In documenting various end-user applications written in OO languages,
I do not use object terminology. The user does not need to know that
selecting file>print creates an object of class printObject... That's
needless info and will only get in the way (IMnsHO).

The biggest change that OO technology has brought along with it is
the GUI and the event-driven program. These outward manifistations
of OO technology have had a much bigger impact on product documentation.
Back in the old days of menus and command lines, your menu structure
became your outline. User actions and program flow were easily
defined because they were so limited in scope. Communication on the
screen was limited, so product documentation had to fill in the
blanks on paper.

Today, communication begins with the product metaphore and continues
through the use of icons, toolbar buttons, status line prompts,
balloon help, online help, and so on. The user is inundated with
information before ever opening the manual! The job of the technical
communicator has increased in scope as the program's ability to
communicate has increased. And it really hasn't made our job any
easier! Standardizing terminology for mouse movements has been one
of the most difficult things we've ever tried. We're still not done!

Perhaps we've tried to hide OO terms from the user a little too
much, but I don't think so. The average computer user doesn't care
how the program is put together, only that it helps get the job
done. As technical communicators, we need to keep that in mind.

Just my $.02 (a bargain at twice the price ;-) )

Sue Gallagher
StarBase Corp, Irvine, CA
sgallagher -at- starbasecorp -dot- com


Previous by Author: Re: On-Line Help (Windows) Book?
Next by Author: Re: Pre-Press at Printers and Publications Tools
Previous by Thread: Object-oriented Programming (OOP) Terminology in Documentation
Next by Thread: FrameMaker and Online Help


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


Sponsored Ads