JoAnn Hackos, PhD
Bill Hackos, PhD

We’ve recently noticed a disturbing trend as we talk to people who are moving to modular writing and XML. Organizations are eager to report their rapid progress. They explain that they have contracted with a content management vendor not only for the software but also for the service of converting their books to modular form and XML. Others have contracted with system integrators or other consultants to create DTDs based on the structure of their existing books.

Initially the authoring organizations are thrilled. “We’ve been able to modularize and convert everything without involving our own staff, and at a reasonable cost!”

We’ve seen the results of these efforts. The modules are often unusable for reuse by the authoring group because they are not modules but little portions of a book. We’ve attended vendor demos in which the sales staff proudly demonstrates a process which produces a module beginning with “Furthermore…” The converted modules are absent any metadata that could be used to look for reuse. The only useful thing that authors can create from these modules is the same book that they had when they started!

Not only are the converted “modules” unusable by other authors but they are worthless to the users of the documentation. The tradition of book development means that information is designed to be used in a linear manner. We don’t need to read a book from cover to cover, but the linear sequence of content in a book inevitably contains information required for the understanding of subsequent content. I’m sure you’ve all seen help systems produced by software tools and consultants breaking a book into modules to create help topics. Without the information contained in the linear structure of the book the help was taken from, we usually find the information frustrating and unusable as individual help topics.

What has become increasingly obvious—there’s no free lunch. Moving from traditional book authoring to modular, XML authoring can’t be done without a lot of hard work. I like to compare it to a weight loss program. We all would love to lose weight without pain. We look for the easy diet or the magic pill. Unfortunately, researchers tell us that the only real way to lose weight permanently is by changing our lifestyles. We need to eat a sensible diet and get adequate exercise. Unfortunately, changing a life style is hard work and few of us succeed.

The only way to move to modularized reuse and XML is through hard work. We need to observe and analyze our users. We need to discard information they don’t need or use. We often must discard much of the content of our existing books and start developing structured, reusable modules from scratch. We need to develop effective metadata. We have to create DTDs based on the structure we want for our modules, not DTDs that simply copy the book structure and the format mistakes contained in our existing books. In short, our organization must make a lifestyle change, as difficult as that may be.

Despite the challenge, the rewards are great. With structured writing, we get superior information, often much better developed to serve the needs of users and far more consistent in our approach to content.

Remember, no pain, no gain.

Start with a structured writing program based on a minimalist agenda. Find the best way to convey the information your users need in a topic-based, modular form. You’ll end up with flexibility and strength, in addition to cost savings, productivity increases, and a very proud staff.