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: Use of Object Oriented Programming Terms in Documentation
Subject:Re: Use of Object Oriented Programming Terms in Documentation From:"Johns, David" <14615johns -at- KCPBLDG05 -dot- BV -dot- COM> Date:Mon, 10 Oct 1994 17:20:00 CDT
Perhaps a rose shouldn't be called a rose until the private data fields
(color, size, smell, etc.) are initialized by the object's constructor or
passed into the object by the user (smeller?). In this context, could we
call the gardener a floral programmer?
If the printer is an object (class if not instantiated), the printer's
attributes, such as paper trays and settings, would be fields (private or
public) within the class.
I would not use OOP terms unless writing for programmers, however. I'm
writing software manuals for end-users, so I try to keep things as simple as
possible--assuming that computer illiterates are the common denominator.
I'm taking a class in C++, but I try to separate the OOP jargon from the
manual writing. I don't try to explain what goes on inside the mind of the
computer.
Dave Johns
Black & Veatch
----------
From: TECHWR-L
To: Multiple recipients of list TECHWR-L
Subject: Use of Object Oriented Programming Terms in Documentation
Date: Monday, October 10, 1994 3:20PM
Should a rose be called a rose or should a rose be called an object
with attributes such as color, size, smell and so forth. Perhaps
more simply stated, when you are documenting an object oriented programming
(OOP) product, should you use OOP terms to describe functions?
For instance, we have an object called a physical printer that has
many attributes, such as paper trays and so forth. Do you all call that
printer a "printer object" and the paper trays a "printer object attribute"?
Since a physical printer is represented by a collection of information that
we call an object, it makes sense to use the OOP terms but how many
people, who want to submit a job to a printer, or who want to make sure the
printer is not jammed, care about OOP terms? As a writer, use of OOP terms
makes it easier to explain the relationships between the physical printer,
the logical printer, and other collections of information. But some folk
seem to think OOP terms are too conceptual for most readers.
If you are writing about a product that uses OOP technology, could you post
a note? And can you answer this question: "Do you use the word object in
your documentation?"
