Symposia• OO-La-La: Object-Oriented Development And Technical CommunicatorsAbstractNew technology is constantly appearing—both on the horizon and in our midst. Occasionally this new technology requires new work habits. Object-Orientation, one of the hottest new programming buzzwords, is just such a development. Bonni Graham will discuss the major themes of object orientation, and how we as writers can use the themes themselves to create documentation more appropriate to this new system. “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:
Many systems claim to be object oriented, but without the above components, they cannot achieve true object orientation. ObjectsThe foremost element of object orientation is the object. Objects are software packets that:
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:
These items enable the flexibility and ease of use that is the hallmark of object-oriented systems. MethodsIn 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). MessagesWe 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 message “drive forward” to the driver (you). The driver uses you implement a method to send the message “go faster” to the engine. The engine uses a method to go faster. ClassesLike 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. Object 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. InheritanceAs 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 lunch, go to sleep, etc. Every instance of subclass Driver knows how to do all that, plus how to drive a car. EncapsulationOne 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. PolymorphismWe 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 is called “drive” in every case. What Object Orientation Means to the WriterOne of the strongest arguments in favor of object orientation is that it leads to programs that are:
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:
Treat Documentation as ObjectsIdentify 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 FunctionsEach 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 1 of 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 FeaturesGroup 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 PolymorphismPolymorphism 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 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. ConclusionYou 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. About the Author…Bonni Graham began writing as the "Lone Writer" for Data Trek, Inc., a library automation developer. She then moved on to Easel Corporation's ENFIN Technology Labs, working on object-oriented client-server development environments ("OO-La-La"). Currently Bonni owns a documentation business, Manual Labour, with clients like Hewlett-Packard, Xerox Document Sciences, and Tudor Publishing Company. For more information e-mail Bonni.
|
Send mail to Webmaster
with questions or comments about this web site.
|