Tools of the Trade: Part Four of a Series. The Big Picture: Implementing Managed Content Sharing

Home/Publications/Best Practices Newsletter/2002 – Best Practices Newsletter/Tools of the Trade: Part Four of a Series. The Big Picture: Implementing Managed Content Sharing


June 2002

Tools of the Trade: Part Four of a Series. The Big Picture: Implementing Managed Content Sharing

CIDMIconNewsletter David Walske, David Walske, Inc.

Map or Recipe

Best selling author Douglas Adams wrote of a time in his youth during which he hitchhiked through Europe. One day he set out on foot to find a particular address in the city of Innsbruck, Austria. Having no city map and speaking no German, Adams braced for the difficult task of asking strangers for directions, but he was ill prepared for what he encountered next. Stopping a passerby at random, he found communication all but impossible. Adams writes, “Gradually the truth dawned on me as we struggled in vain to understand each other that of all the people in Innsbruck I could have stopped to ask, the one I had picked did not speak English, did not speak French, and was also deaf and dumb.” He stopped another man who, as it turned out, was also deaf and dumb. He stopped a third stranger and then a fourth, all deaf and dumb. Reeling from this seemingly impossible chain of events, Adams explains, “If I hadn’t happened then to duck down a side street and pass a hotel where a convention for the deaf was being held, there is every chance that my mind would have cracked completely and I would have spent the rest of my life writing the sort of books for which Kafka became famous and dribbling.”

Traveling on business as many of us do, we’ve all probably found ourselves struggling to navigate from one point to another in a large and unfamiliar city. The simple task of finding an office building or conference center can be daunting when you’re unfamiliar with the route. A map can be a big help. With a map and a little information, you can plot your route in a linear fashion and find your way. But what if you want to stop along the way to have lunch? How can you find the best Tandori Chicken within six blocks of your destination? Your route map probably won’t be much help. A travel guide can give you an alphabetical list of Indian restaurants, but if you don’t know the geography of the city, that’s not going to work very well for you either. What you really need is more like a recipe than a map. You need a guide that gives you the “ingredients” of the neighborhoods through which you pass. (See below.)

Access Travel Guides

Access travel guides are a cut above the average travel guidebooks that you might commonly pick up in a bookstore or airport gift shop. Instead of using alphabetical order or an organization based on categories such as hotels, restaurants and so forth, Access guides are organized by neighborhood. Thumbing through one of these guides, such as Access San Francisco, you feel as if somehow you were magically transported to the delightful neighborhoods of the “city by the bay.” To actually stand in one of these neighborhoods with the guide in your hands makes you feel as though you’re touring the city as an insider. The best shops, restaurants, and hotels greet you like old friends. Fascinating side stories and historical background items punctuate the pages of the book, further elevating you above the typical tourist experience. It is largely the unique organization of the Access guides, however, that makes these books such treasured volumes.

Both maps and recipes have their place. Information is sometimes presented in the form of a map. The typical table of contents that we employ in our document-centric approach to information development is a map, or template, of the content contained in a given book or chapter. The typical index is a little like the average city travel guide, listing information in categorized alphabetical order. These kinds of structures are valuable, in fact necessary, at the document level but fail to address the interrelation of information at a more global level. Successful content management-that promotes content reuse and repurposing to multiple formats-takes the next step, pushing beyond the limitations of chapter and book constructions to encompass a modular information model. Like a recipe, a modular organization specifies the ingredients and their combination, but not the shape of the cake. Previous articles in this series explored XML and SGML schemas, which describe the structure of information but not a specific document or the content that it contains. Article number three in this series, “XML Transformation,” demonstrated the use of XSLT to import content into a template to create a document instance. (You can read the third article in the April 2002 issue of Best Practices.)

This, the fourth and final article in the series, explores content-management techniques that help to bridge the gulf between the document-centric needs of specific deliverables and the enterprise resource management issues of content creation and reuse. The database managed information-development process supports reuse by setting database pointers to existing content elements instead of copying them over and over again from document to document. This kind of managed reuse reduces the cost of information development while increasing the accuracy, uniformity, and timeliness of your documentation.

Information Design

Because information models do not live in a vacuum, we’ve used sample content in each of the preceding articles to demonstrate document structure specification, legacy document conversion, and XML transformation. We’ll continue from the last article using sample documentation for the fictional product PrintRight Laser Printer Optimizer. But this time, we’ll envision this software program in a family of similar products, delivered to market in both stand-alone and suite editions, for three different computer operating system platforms.

We’ll create our fictional software line by adding two additional imagined products, ScanRight and CamRight, to our original flagship program, PrintRight. Each of these products, with one exception, is available for Microsoft Windows©, Apple Macintosh©, and Sun SolarisTM. The CamRight product is not offered for use with Solaris. These software programs are also grouped into suite products on each of these platforms. Our fictional product marketing group has chosen to express the product line as a matrix. (See the table.)

AllRight Optimizer Product Line












PrintRight Light
ScanRight Light

PrintRight Light
ScanRight Light

PrintRight Light
ScanRight Light

The products have similar but not completely identical functions. The light versions have limited functionality and no user interface (UI). When a suite is installed, the UI is presented as a part of an integrated suite UI. Each product is also available as a stand-alone installation. Except for the light versions, stand-alone products each have an individual UI.

Organizing principles
To the marketing group, organizing the product line as a matrix, delineated by packaging and platform, seemed perfectly logical. And from a sales and marketing perspective, it is quite appropriate. Potential software consumers can easily determine which product configurations are available for each of the supported operating systems.

The depth and breadth of information in this world is limitless. The ways in which it can be organized are not. This may sound hard to believe at first, but there are a total of five organizing principles. Information architect, Richard Saul Wurman defines them as, “LATCH: The five ultimate hatracks.” They are Location, Alphabet, Time, Category, and Hierarchy. Sort any set of data, and you’ll end up using one of these five. Of course, each of the five principles can be reused as sub-sort criteria to create up to twenty-five unique combinations. The marketing department’s matrix is a combination of category and hierarchy. The same organization that they visualized in table format could also be represented in a categorized hierarchy. (See the figure.)


Organizing a documentation database using a hierarchy would be very tempting. It would also be a mistake. This organization does not best represent the interrelationships of the information elements for optimal reuse. Content authors would have a hard time visualizing how to effectively share content in a database arranged in this fashion. Simply locating elements for reuse might prove to be a difficult task.

Specifying document structure
In the first article of this series, we sought out the inherent patterns in content to find its natural structure. (You can read the first article in the December 2001 issue of Best Practices.) To begin to specify the structure of our database, we’ll first need to go back to the document level. Let’s take a look at an individual table of contents for one of the documents in our documentation base to get a sense of how we might better organize our database. Each of the suite products uses a similar document construction, so we’ll need to examine the table of contents of only one document to get a sense of them all. (See the figure.)


We’ll specify a Document Type Definition (DTD) to serve the needs of specific documents as well as the database in general. A cursory document analysis provides the following insights. The bulk of the content has to do with understanding, configuring, and using three similar but distinct technologies: the first having to do with printing, the second with scanning, and the third with digital cameras. Additionally, there is content about installation and the UI, which in the case of suite products is unified by a single dialog. One possible approach to database organization might be to structure our database primarily around the specific functional areas of the individual software technologies: printing, scanning, and digital photography. Next, we’ll see what this might look like in an actual database.

Database Organization

The underlying technology here could be any suitable XML or SGML database application that is designed for use as a content-management repository. We’ll be accessing the Astoria database from Lightspeed Interactive and we’ll access the elements contained therein, using The Environment by Ecosystems software. This program sits on top of the content-management database, providing a UI as well as additional features.

Building core content categories
We’ll create the core content categories first, by establishing database folders named Printing, Scanning, and Photography. The folder names are intentionally broad. The product line already includes light versions of some of the software products, and there will likely be additions in the future. By avoiding the use of product names in naming categories, we help preserve future scalability. We’ll also create one or more folders for common content that is not specific to any particular subject area. This could include front matter and other boilerplate items as well as an area for content created outside the documentation group, such as content from software development or marketing. (See the figure.)



Our high-level database organization is based upon subject-matter categories rather than product names for maximum modularity and scalability.

Bursting at the seams
Ideally, content-management repositories are composed of granular modules of information. We need to effectively manage content at the sub-document level. Compare this to modern physics. If we were unable to manage physical elements at the sub-atomic level, science might find it difficult to distinguish cesium from sodium or lead from lithium, other than by the deleterious effects that would surely result from such mystery.

As we move our structured documentation into a database, a bursting action shreds content into sub-document elements. Yet, content authors tend to think in terms of whole documents or chapters. Successful content-management strategies bridge this gap, allowing authors to work in a familiar and comfortable fashion while adding the value of managed content sharing. No matter how ingenious the content-management system, if the UI and workflow process is too foreign or too difficult to master, it will not stand the test of time in the real world of the content author. We must have a marriage of technology and people in which both partners bend slightly to each other’s needs. The software must accommodate the human factors of the writing process. The writer must learn how to write to a modular deliverable. Software documentation managing editor Jennifer Brawer states, “Fundamental to content management are writing standards that define detailed guidelines for writing modular components.”

Managed Content Sharing

So how do we begin to share content in a modular way without alienating the content author? From the content authoring perspective, not that much has changed; we’re still working with and delivering documents. The author is most likely still working primarily in a familiar word processing program to create and edit content. The difference is the way in which we manage sub-document elements and how we share content between documents.

Subtractive vs. additive
There are two types of managed content sharing: subtractive and additive. With subtractive content sharing, we create a new document by starting with an existing document that is stored in the database, pruning out what we don’t want, and inserting new content that we want to add. This is sometimes called a “top-down” approach because we start with a high-level structure and work our way down through the subordinate elements. With additive content sharing, we do just the opposite. We create a new document by picking and choosing subordinate elements from the database, piecing them together, and inserting new content that we want to add. This is sometimes called a “bottom-up” approach. Most documents are created and maintained using a combination of subtractive and additive content sharing.

The AllRight Optimizer product line is dominated by suite offerings, but at the core of the suite, we find three stand-alone products. We’ll start by importing the user guide documentation for the stand-alone products into respective categorized folders. Having completed this task, we will have populated the database with a large amount of core content from which to glean elements for reuse.

Creating suite documentation
Most of the content for our AllRight Optimizer document already exists in the database. The three stand-alone content areas that we created include most of what we need. Also, the PrintRight documentation uses an overall structure that is suitable, with a few changes here and there, for the suite product documentation. Therefore, we can model our new document on the existing PrintRight documentation. We’ll use the Live Outline® feature of The Environment to selectively reuse content from the existing document. (See the figure.)

Using a combination of subtractive and additive content sharing is a highly effective way to yield maximum reuse benefit. If limited to a strictly additive process, the content author would have to laboriously select each lower-level element in order to assemble a new document. Live Outline supports the subtractive content sharing process, while other features of The Environment, such as Directed Graph (see the figure) and complex search capability, support the additive process. To create the documentation for the light versions of the three core products, would you use an additive, subtractive, or combination content sharing process? You would most likely use a subtractive content sharing process.

Further Exploration

From document structure specification, through the perils of content conversion, to XML transformation, and finally with this article on database organization and managed content sharing, we have come full circle in the content-management life cycle. This article has presented one possible database organization for one specific fictional documentation base. Your approach to modular information design must be tailored to your unique content, software, hardware, and authoring requirements. CIDMIconNewsletter

About the Author