Building Informative Objects: Excerts from Hot Text—Web Writing that Works!

Home/Publications/Best Practices Newsletter/2002 – Best Practices Newsletter/Building Informative Objects: Excerts from Hot Text—Web Writing that Works!

CIDM

February 2002


Building Informative Objects: Excerts from Hot Text—Web Writing that Works!


CIDMIconNewsletter Jonathan Price, President, The Communication Circle, LLC

Think of an object as a little creature that has only one purpose in life: to apply certain methods to a specified collection of data.

-James Martin

The biggest change for writers moving into the world of XML is that now you must think more rigorously about structure, creating little Lego bricks of content, destined to be assembled and reassembled in ways you cannot always anticipate. You are no longer making a single document; you are preparing objects that can be put together in many different structures, formats, and media. But what is an object?

Programmers have their own ideas of objects, described in pattern languages and documentation. But as a writer you want to create chunks of text to communicate: You are making informative objects.

From a writer’s point of view, objects have seven characteristics that make them informative. We’ll cover those here. If you are familiar with object-oriented programming, you’ll recognize the analogies here. But even if you don’t live in an OO environment, you’ll begin to see some of the benefits-and the challenge-of organizing your content in objects.

1. Each Object Starts Life as a Category of Content

Each object is defined abstractly as a class, such as a Procedure. The abstract object is an ideal notion, like a Platonic form-a category of information. As soon as you write something, you are creating an instance of that class-a unique example of the class, a particular real object.

2. The Class Has a Standard Structure

The class defines its components in a certain sequence within a single hierarchy. The standard tells us how many components are allowed, or required, in what order, and which ones are just optional. The relationships between objects are defined in a content model, known in XML as a Document Type Definition, or schema.

Every instance of that object must follow the same internal pattern. That regularity allows software to maneuver quickly through the object’s content, locating the subcomponent it wants; but a human writer may find the rigid structure uncomfortable and constricting.

3. Each Type of Object Has a Job to do

The responsibility or function of each informative object is, in its simplest form, to respond to a particular type of question, such as, “What are the results I can expect if I do this step?” (Answer: an object called an Explanation.)

Over the centuries, writers in any genre have invented common elements to answer the kind of questions that keep coming up. For instance, in creating procedures, writers came up with a standard element to answer the question, “What do I do next?” That element, the step, shows up in so many manuals that we can now say it is conventional. Turning a routine element like that into an object is easy: we recognize the element from our reading, and we are simply blessing it with a new description and a new role. Informative objects, then, are often familiar elements, doing a traditional job in new clothes.

Price fig 118

4. Objects Talk to Each Other

Being electronic, and living within a world of software, each object can exchange messages with other objects. Yes, these objects can link up. Basically, one informative object sends a message to another saying, “Will you display yourself?” If the linkage works, the other object shows up on screen. Unlike the complexity of messaging between heavy-duty programming objects, this little exchange is essential to our job, as creators of interactive text.

5. The Same Object Can Be Reused in Many Different Locations and Media

Each object can be used as a component in other objects, placed in a different position in a sequence of objects, or used without some of its optional components.

Reuse goes more easily with objects because

  • We can use exactly the same object in many locations without rewriting it. (This kind of reuse can save hours of our time and thousands of dollars in the budget.)
  • We can select certain objects to send out to a handheld device, others to go to a Web page, and still others to be printed out on paper, simply by picking a different Document Type Definition or stylesheet-without any rewriting.
  • When updating material, we can search for a set of objects by class name (Give me all the steps in this long procedure). That way we can make a change in the steps without having to paw through the intervening explanations.
  • We can take apart an existing object and use selected components, but not others, in a new object.

6. Searches Can Turn Up Individual Objects, Thanks to Attributes

Attributes describe the object (see the figure below). For instance, the Procedure object has attributes, such as subject, and owner; when you create a new procedure, you fill in the blanks with the new subject and the person who “owns” that particular object.

Price fig 220

Each class of objects has a set of attributes, like fields on a record in a database, and each instance of that class has its own values, in those attributes. The point is to allow users (and writers) to search on values in a variety of attribute fields, such as

  • genre
  • subject
  • owner of the information
  • date created or modified
  • subject-matter experts or authors
  • products named
  • product ID
  • natural language used in the writing
  • operating systems this product runs on

7. Objects Can Be Assembled Quickly, Creating Personalized Content

Personalization demands that you break up your content into small chunks, so you can deliver just the pieces one person wants without the annoying extra details they would like to avoid. Customer relationship management, Web application server, and customization and personalization programs can track individual visitors by their cookies and offer personal welcome pages with customized content, including topics the person has indicated interest in-but only if you have carved your material up into a lot of bite-sized chunks.

Taking an Object-Oriented Approach to Structure Cuts through the Noise

Looking at the elements in current documents as informative objects can help you improve the effectiveness of your writing. Having an object model to work with (taken from the DTD), you can do a number of things that tend to make your writing more alert. You can, for instance

  • Define the purpose of each object you use, so you can include only what is relevant and leave out the interesting but extraneous details that confuse people.
  • Follow the standard pattern for these objects, so readers (and programs) know what to expect and do not get derailed by strange variations.
  • Apply that pattern in editing old documents to spot places where the document is not working properly, correcting those passages without getting lost in stylistic revisions.
  • Create team templates that restrict and direct new writing.
  • Build in attributes that allow more pinpointed searching for particular small objects, such as a definition or a single procedure. You are making it possible for software to filter out thousands of near misses and duds, focusing on the particular type of object you or your users want.
  • Make your conceptual model explicit and articulate. Exposing your structure generally makes for faster reading and better comprehension.
  • Support the users as they grasp and use the structural model you present by being consistent in your own use of it, avoiding internal inconsistencies that raise questions in people’s minds.
  • Offer multiple perspectives on the same information and various possible organizations on different media.
  • Identify possible audiences for particular objects, using an attribute such as Audience.

The Web drives your organization to take traditional types of documents, such as the data sheet or procedure, and standardize them, defining each one as a distinct genre with a clearly articulated purpose, audience, subject, and organization. At first, moving into this environment feels constricting, artificial, and a bit abstract. But after a while, you’ll probably find that your writing goes faster, gets cleaner, and does its job more efficiently because you know what the purpose of each object is, understand what kind of question it answers, and you do not get distracted, drawn off on a detour, or just plain confused about what goes where. You begin to think structurally, and interestingly, that often leads to uncovering new facts, understanding your subject in more depth, and shaping your material for the benefit of your readers, not yourself or your teammates. What you give up in originality, you gain in impact. CIDMIconNewsletter

About the Author

BPFebruary02a7