Writing in modules-the future or a meaningless diversion?

Home/Publications/Best Practices Newsletter/2007 – Best Practices Newsletter/Writing in modules-the future or a meaningless diversion?


June 2007

Writing in modules-the future or a meaningless diversion?

CIDMIconNewsletter JoAnn Hackos, CIDM Director

At the XML 2006 conference in Boston, Jon Bosak made some very negative comments about modular document authoring in his closing keynote. He claimed that

“Another ancient subject that seems to be popping up again is the idea of modular document creation. This is one of those concepts that comes through about once a decade, seduces all the writing managers with the prospect of greater efficiency, takes over entire writing departments for a couple of years, and then falls out of favor as people finally realize that document reuse is not a solvable problem in document delivery but rather an intractable problem in document writing—which is, how to retain any sense of logical connection between pieces of information while writing as if your target audience consisted entirely of people afflicted with ADD.”

Bosak notes that he hasn’t had much connection with documentation development since 1978. He seems to have missed minimalism, online help design, Information Mapping, and other work that has contributed to our understanding of how people use manuals. He remarks that modular authoring technology such as DITA is “virtually guaranteed to buy tech writers a few years in which they can act like software engineers and present themselves as engaged in cutting-edge information technology development rather than plain old technical writing.”

For the past few months, several people have been engaged in a discussion based on Bosak’s remarks. Bill Hackos, Michael Priestly, Bob Doyle, Bruce Esrig, and Troy Klukewich, as well as other CIDM contributors, have taken issue with the disdainful and largely backward looking remarks. Bruce suggests that we turn our attention forward to understanding the needs of users who are concerned not with reading books or manuals but with solving their problems and getting answers to their questions.

At the most fundamental level, we must acknowledge that, except for the accident of printing and binding, technical product manuals are not books. They have resembled traditional books, university textbooks perhaps, in the way we write them, but they are not used in the same way or for the same purposes. As Bruce notes, “story-based documentation writing is inefficient unless a critical mass of readers needs to learn the same things in the same sequence and at the same depth.”

Rather, we know from frequent direct observation of user behaviors that users want to access the content that supports their immediate learning needs. They want to answer the questions that Bill Horton helped us pose in the early 1990s when he focused our discussion of help system design on key user questions. The list is familiar to all of us:

  • How do I …?
  • What is …?
  • How does it work …?
  • And so on.

Modular writing, developing discrete, standalone topics rather than chapters of books, requires that we respond attentively to the user’s questions. If we follow best practices, we plan the topics that will be written and consider the relationships between the topics. We construct ditamaps and relationship tables before we deconstruct and write individual pieces. As Susan Harkus mentioned in a recent discussion on the CIDM listserv, we develop “atoms” of information that can be assembled into a wide variety of “molecules,” depending on how the user thinks about and needs to review the information.

Our primary goal today in developing technical information is to understand the problems that the users are trying to solve and provide them with multiple possible paths through the information. Modular writing allows us to present the results of our understanding in consistently written nuggets of information. Users can reassemble the nuggets to match their own goals. Users think through the information in the way that makes the most sense to them. The writers must plan and anticipate some of those thought processes while acknowledging that all can never be completely known. Writers who receive feedback from users begin to understand that their perspectives on learning are indeed more complex than we have ever imagined.

If we can learn how to isolate elements of information to respond to particular user needs and we can provide meaningful links to other elements of information, we have the opportunity to develop a meaningful resource. Users profit from our attention to the atoms and their interrelationships. We profit from developing information that makes a difference to our customers.

We know that the traditional methods we have used to build books have largely been unsuccessful. As I review documents for the many organizations I work with, I note that much of the content was simply dropped into a holding place. So-called concept material is especially problematic. Most of it seems to have been copied from other sources and awkwardly stitched together. Writers find content in product specifications, market reviews, user requirements documents, and other resources and copy the chunks into a chapter of a larger document. The result is a disjointed collection of barely related topics that don’t add up to an meaningful conceptual framework.

The “concepts” often are nothing more than a list of features, with descriptions and sometimes definitions, all treated somewhat differently. Rarely does a coherent story result, even though some users would profit from a coherent story that provides a sound conceptual framework. Just think how refreshing it would be if we could understand how the numbering system works in MS Word. In addition, the vaunted authorial voice that we claim is so important to readability is frequently absent because the original writing was done by numerous authors and never adequately integrated.

Generally, we do much better with procedures, but they too suffer from too little understanding of what users really need to know. We write about navigating from one screen to the next or filling in fields in dialog boxes when the users really want to know what the implications of their choices will be and how they can make the best choices to further their goals.

The best practices in our profession are clearly moving toward topic-oriented, modular writing. Not only is it efficient in terms of reuse or translation cost savings, it actually promises to be better than anything we have done before. As part of the process, we focus our writers on content rather than desktop publishing. We simplify the review process by asking experts to review small topics rather than hundred-page tomes. We find errors more quickly. Troy Klukewich reports that he saw a 30 percent improvement in productivity when his department moved to modular authoring, largely by overcoming the inefficiencies of the desktop publishing, book-oriented processes.

We also see the enthusiasm with which DITA has been embraced by the information-development community. At the same time, we recognize that our departments and our information developers have to relearn their trade. Writing effective modular content is hard work, much harder than cutting and pasting content from external sources or tweaking the format. It demands close attention on the user at a level that has not been part of most writers’ experience in the past 30 years. Perhaps, it also demands more of our users. They are being asked to engage in an active learning experience. Conveniently, they have long been asking us for better information that helps them meet their goals.

It’s no accident that people generally dislike or disregard our documentation. It’s popular to claim that one has never looked at the manuals. Our growing focus on the user, as demanded by modular authoring, may turn the tide of opinion in our favor.