TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
