OO & Doc (long post)

[Bonni Graham <bonnig -at- AOL -dot- COM>]

Ok, y'all asked for it.  The following is the text of the paper I described
in earlier posts about using OO concepts when writing doc.  The first half of
the paper described the OO concepts themselves, so if you're already familiar
with them, you can skip that.

As I mentioned earlier, this is only the text.  If you want the handouts,
which illustrate the concepts I'm describing here, you can send an SASE
($0.52) to Bonni Graham 4115 Wabash Ave. San Diego, CA 92104-2124.

OO-La-La:  An Introduction to Object-Orientation for Writers

"Oooh!" I said, the first time I saw my new company's software, admiring its
ease of use.  Yes,  my boss said, "OO."

OO is the acronym for one of the hottest "new" software concepts, Object
Orientation. OO has, in many ways, turned the software industry on its ear,
by providing the answers to several long-standing problems  with more
traditional structured programming. For example, changing a data structure in
a structured  program can break other portions of code, even if they're in
another module. In OO, these sections of  code, called objects, are
completely independent. Change a data structure here, and it usually has no
effect at all on the ability of other objects to continue functioning.

Object orientation inextricably intertwines data and the programs that
manipulate it. In a database, for  example, there is no separation between a
record and the editing screen that allows you to update it. You  don't have
to load the editor, then select a record. In essence, by using OO technology
programs can treat  information the way it appears in the real world.

WHAT IS OBJECT ORIENTATION?

Object orientation is a philosophy of programming that regards the world as
individual elements that can  interrogate and interact with each other,
rather than as a series of procedures and sets of data, as
structured programming does. These individual elements are called, of course,
 objects.  They are  organized into classes, which sort objects with similar
functionality into groups. Objects use messages to communicate with each
other, and methods to perform the actions requested by messages. True object
orientation support the following concepts:
o  Inheritance
o  Encapsulation
o  Polymorphism
Many systems claim to be object oriented, but without the above components,
they cannot achieve true object orientation.

Objects
The foremost element of object orientation is the object. Objects are
software packets that:
o  are unique (like real-world objects)
o  have certain attributes, or data
o  exhibit certain behavior.
Take, for example, your car. It is a member of a class, called MotorVehicle,
which also include objects  like Boat, Motorcycle, and Airplane. Each motor
vehicle is different from each other system (is unique), is made up of parts
(attributes), and performs actions (behavior).

Once you have objects, they need to interact with each other. OO programs do
this through:
o  methods
o  messages
o  classes
These items enable the flexibility and ease of use that is the hallmark of
object-oriented systems.

Methods:  In the section above, we learned that objects exhibit certain
behavior. They accomplish this by using  methods. Methods are sets of code
that describe the way(s) an object can behave. Objects can include as many
methods as necessary for them to function, but they cannot function in ways
for which they have no
methods.

To continue our car example, the engine knows how to pump the pistons up and
down, move gas through, cool itself, etc. The steering system knows how to
turn the car. You know how to drive the car, eat lunch, write manuals, etc.
(sometimes some of the methods an object can use have no relationship to the
task at hand).

Messages:  We also learned that objects interact. They do this by sending
messages to each other, which invokes a method. The sending object uses a
message to ask the receiving object to use one of its methods to perform a
task that the sending object cannot do. Messages mimic the way things in the
real world communicate.
Back to our example: A traffic light turns green, which sends the essage
 drive forward  to the driver (you). The driver uses (you mplement) a method
to send the message  go faster  to the engine. The engine uses a method to go
faster.

Classes:  Like real-world items, objects fit into different groups, called
classes. Classes assist object orientation to achieve its streamlined
functioning by defining things common to all objects of a particular sort.
This means that the code necessary to define common object information must
only be written once to forever
apply to any object that is now or will be in that class. Objects know what
class they belong to, and can act on that knowledge, since the methods they
use to act are stored with the class. In addition, classes can be broken into
subclasses, where each subclass knows how to do the things from the class
above and all the things from its own class.

Your car is an instance of the superclass MotorVehicle and of the subclass
Automobile (whether it is a Ford or a Chevy, a sedan or a hatchback). You are
an instance of class Person. That Yamaha that just cut you off is an instance
of class Motorcycle, which is a subclass of MotorVehicle. Its rider is an
instance of class Jerk, which a subclass of class Person. And so on.

Inheritance
As you've learned, objects are grouped into classes that share common
methods. You've also learned that classes can be broken into subclasses that
share both their own common methods and those of the class(es) above them.
This sharing is called inheritance. Inheritance greatly reduces the amount of
code needed to run a program successfully. Once a method is created in a
class, it can be used by that class and all its subclasses. In other words,
the code is written once, not every time a similar object needs it.

For example, every instance of superclass MotorVehicle knows how to go
faster, how to turn, etc. The subclass Convertible knows how to do everything
that class Automobile does, plus it knows how to lower
its fabric roof. Every instance of class Person knows how to eat unch, go to
sleep, etc. Every instance of subclass Driver knows how to do all that, plus
how to drive a car.

Encapsulation
One of the ways object orientation is superior to structured programming is
due to encapsulation. In the introduction, I mentioned that changing a data
structure for a class of objects usually had no negative effect on how (or
whether) other classes of objects function. This is because encapsulation
ensures that each object's internal structure is hidden from other objects.
Because of encapsulation, all an object must do to interact is send a message
to another object. The sending object doesn't have to know how the other
object is going to respond or what methods it's going to use.

When you're driving, you probably don't really know how the car goes faster.
The traffic light doesn't know how you stop. Not only do neither of these
items know, they don't care. The real world is
encapsulated.

Polymorphism
We learned that objects use methods and send messages to communicate how to
behave. What polymorphism provides is the ability to call the same function
by the same name, even though that
function may be performed differently within each object class. This
eliminates much user confusion.

Every motor vehicle can be driven--each instance of class Person (you) must
simply include the method driveMotorVehicle. Each motor vehicle implements
the message "go faster" a little differently, but each can be driven, and
each driver can drive, and the function used to do it can be called  drive
in every case.

WHAT OBJECT ORIENTATION MEANS TO THE WRITER

One of the strongest arguments in favor of object orientation is that it
leads to programs that are:
o  reusable
o  flexible
o  maintainable
o  easily evolved as needs change
What we need to do as writers for object-oriented systems is learn to
structure our documents so as to make them meet the above standards. Part of
how we can do this is to use some of the very techniques that make object
orientation so successful:
o  treating items as objects
o  encapsulating internal functions
o  inheriting features from other classes
o  incorporating polymorphism to make features as reusable as possible

Treat Documentation as Objects
Identify the tasks your users will perform and write the documentation to
reflect that. Although this is a basic rule of good manuals, in the case of
structured programs it often stands in direct contradiction to
another basic rule of good manuals, which is to try to organize the manual in
the same way the user interface is organized. In object-oriented programs,
the user interface isn't really organized it's presented.  Programs tend to
be drag-and-drop, rather than menu-driven, so users can use any object on the
screen at any time and in any way they choose.

Think of the set of instructions to perform each task as an object: it should
stand on its own and contain every behavior (method) needed to work properly.
It can be part of a larger set (a chapter, for example), which contains more
general instructions to accomplishing this task and others, but it should
always be ready to send the user to another task's description, if necessary.


Encapsulate Documentation Functions
Each piece of the documentation set (user guide, reference, tutorial, online
help, etc.) should stand as comprehensible on its own, containing as much
information as necessary to the type of manual, but no more. As an English
teacher of mine used to say, when we'd ask her how long our papers needed to
be, "As long as necessary, but as short as possible." Granted, this was not
tremendously helpful to tenth-graders, but it is a good guideline for
professional writers.
The above piece of advice may seem obvious, but it's surprising how hard it
is to follow, and it has one very important ramification: Information should
almost never be repeated in an object-oriented
documentation set. If it's in the online help, it should not be in the user's
guide. If it's in Book 1of the guide set, it should not be in Book 2.

But, you might say, my users won't have read the earlier (or later, although
you probably want to avoid forward references) section. That's where you use
another feature of object orientation messages. Cross reference everything.
Send them to the online help from the user guide for specific data entry
details.
Send them to the user guide from the online help for procedural information.
Send them to glossaries, appendixes, tutorials. Don't overuse
cross-referencing (i.e., don't define your documentation objects too
narrowly), but don't be afraid to use it.

Inherit Documentation Features
Group similar task descriptions into chapters, and have the first section
describe behaviors common to all tasks. That way you can describe the
procedure to save a query at the beginning of the chapter, and at the end of
the description of each query have a single, simple instruction that says
"Save." Or put all the
tasks that manipulate queries in a chapter, describe how to create a basic
query, then say "Step 1: Create a query."

Incorporate Polymorphism
Polymorphism is most effectively used in online documentation: write the
description of how to use the Save button or the Open dialog once, then
hyperlink to it. Since object-oriented systems often use
dynamically created dialogs (dialogs that have the same base, but with
features that are added or removed depending on the selection made), create
field-level context-sensitive help. Those fields will probably appear often
in the program, in wildly different places, so only write them once.

An aspect of polymorphism can be used in paper documentation as well: use
Simplified English (or a reasonable facsimile thereof) as much as possible.
This has always been somewhat of a problem for me. As a writer, I want to
read manuals that have elegantly structured sentences, that use the
techniques the great masters of literature use. As a software user, I want
the manual to tell me what I need to do, then get out of my face. A co-worker
of mine put it very succinctly: "If they have to look it up, they're already
mad." If you use simpler English, you can always refer to items using the
same terms (and not feel guilty), the way that object-oriented programs use
methods that are always called the same name if they perform the same
function. Your user will understand what you mean faster, and stop being
 mad  sooner.

CONCLUSION

You may already be using the techniques I've described above. You may have
been using them all along, regardless of the object-orientation of the
program you're documenting. If you have, great--you've already discovered
reusability! If you didn't realize that these were similar to object
orientation, you now have a more familiar way to view OO's components. If you
haven't been using them, or if you're just starting in OO, these writing
techniques can help you to create documentation that matches both the
structure and the philosophy of the programs you write about.
***

So there you have it.  Writing in a closely-defined OO way will not be
appropriate for every book.  But at least thinkling about the doc in an OO
way gives you one more alternative way to think about the doc and create a
book that best matches your audience needs.

Hope you enjoyed this!

Bonni (I think you all know who I am by now...<grin>)
BonniG -at- aol -dot- com