How to Rewrite Content for Reuse

More than just discussing why reuse is valuable, in this article from DCL News Pamela Kostur tells you how to do it. Pamela advises on how to convert your unstructured (or loosely-structured) legacy documentation into something more suitable for reuse. Why not just re-write everything from scratch? For starters, it’s cheaper to re-organize previously-written materials than to start all over, and it’s safer to use documents that have already been used in the field and already been tested in the line-of-fire.

However, restructuring is more than just “fitting” content into a structure. It often requires some rewriting. Restructuring should be done with a view to moving forward (otherwise, why bother), so it’s best to think of structure that you want, rather than what you have. But, sometimes you have to include some of each. In this article Pamela shows you how to plan an information architecture and move into developing structure and guidelines for a new reuse environment.

By Pamela Kostur, Parallax Communications

When it comes to converting legacy documentation, where possible, I’d advise the following:

Design what you want and roll that new structure out to authors to be used on a “go forward” basis
Try to convert legacy documents as much as possible into that new structure, keeping in mind that you can’t force content to fit a structure. Rearrange where possible; rewrite in others
When designing new structures, start by analyzing the legacy documents. Analyze to see where structure needs the most improvement (e.g., to enhance usability, to assist authors in reusing content); restructure giving the most attention to those areas
Design new structures with existing structures in mind and with a view to how existing content will best convert to the new structures. For example, figure out where large chunks of content can be put into new structures relatively unchanged.

Writing reusable content-and reusing content others have created-is efficient for you, for the company you work for, and for your users. However, writing for reuse is different than “starting from scratch” or from writing in the narrative form that many of us have learned and followed for several years. This article discusses the importance of writing for reuse and provides some guidelines for getting started. It covers these topics:

Why reuse content?
- Issues with reusing content
Planning for reuse
Writing in modules
Following a structure
- Accommodating different uses and users

Why reuse content?
Writing modular content that can easily be reused is important not only when working in a content management environment, but also in the world of “everyday” technical communication. Technical communicators are being called upon more and more to create reusable content and to reuse content that others produce. There are several good reasons to adopt writing for reuse, among them:

Writing for reuse is efficient—It’s costly for several people to create the same product description (or procedure or error message) over and over again. Instead, one person can create it for all uses, based on a standard that accommodates all uses. However, for reuse to be efficient, you need to plan for it and create standards.
Writing for reuse helps to ensure consistency—When the same product description is used for the manual, the online help, and the brochure, you can rest assured it is consistent.
Writing for reuse helps to make content more usable. When writing for reuse, it’s critical that you follow standards, which are based on usability. Standards ensure that similar types of content are structured in similar ways. Everyone writing a product description follows the standard for the product description, making it both reusable and usable.
Writing for reuse helps users to navigate through content—Reusable content is written in modules with clearly defined labels identifying the content’s purpose. Modules can be arranged to accommodate different uses and users; the modularity can also help users to easily identify and select the information they need.
Writing for reuse provides continuity—When users follow a link “for more information,” they expect to see something similar to where they came from. Reusing content can provide this continuity.

Issues with writing for reuse
Although writing reusable content makes sense, it’s not as easy as it sounds, as illustrated in a July 2006 article in The Content Wrangler, in which Scott Abel describes 10 DITA Lessons Learned from Tech Writers in the Trenches, Lesson #5 is “some writers CANNOT write reusable content” and interviewees reported:

Technically, DITA is a very sound approach, but you need to consider the psychological impact on writers. Writing in books, chapters and sections is a very different approach than creating DITA topics and topic maps.
I found that authors who did not understand the reasons behind structured authoring often directly or indirectly resisted the move.
Authoring for reuse is different. Each topic must be authored as a standalone item. If you think this is no major feat for some technical writers to accomplish, a move to DITA will definitely show you who is-and who isn’t-capable of thinking in the way that DITA requires.
The main difficulty writers had was to make the switch to writing topic-based material. We were used to writing documents for a particular product or particular audience where we now write topics which may fit in multiple publications for different products and different audiences.

The theory of reuse is great regardless of how you are authoring your content (DITA, or another method), but the key problem lies in creating content that is genuinely reusable and in helping writers to make the switch. It is not impossible, but there are a number of challenges, including:

You need to plan ahead; you need a reuse strategy based on a thorough analysis of your content. You need to ensure that you don’t compromise content simply to make it reusable.
You need to create and follow guidelines to ensure that the content can indeed be used in different places/different media. Guidelines will help to ensure content is consistent, regardless of who writes it.
You need to make sure that content is identified properly (metadata) so that others know what it is and can find it. If they don’t know what it is or can’t find it, they can’t reuse it.
You may need to create content outside of its context, yet understand that the content will be used within a certain context.

Planning for reuse
Reuse doesn’t just happen-you need to plan for it. Planning where and how to reuse content will help you to overcome some of the challenges. Your first task is to figure out where content will be used. User guide? Collateral? Online help? Handheld device? Web?

Determining where content will be reused and thinking about how it will be structured for reuse is the beginning of your information architecture. The information architecture describes which modules (elements) your information products contain, in what order, and the structure of the individual modules.

Example: You work in the documentation department for a wireless communications company. Your group produces documentation for customers (user guides, brochures, content for the web), for the call centre where customers call for assistance, and for third-party vendors who sell your products. There is a great deal of overlap among your documents, so you decide to reuse content. This will allow you to be more efficient and to ensure that content is consistent wherever it appears.

At a very basic level, the information architecture might look something like this, with M indicating mandatory, O indicating optional, and a blank cell indicating a component is not required in that information product:

Knowing that you will reuse certain components such as product descriptions, you can plan how to structure and write them to support reuse.

Writing modular content
Modular writing allows you to more easily reuse content, whether you are working in a content management environment or not. Modular writing makes sense for several reasons:

Documents can be constructed from modules—For example, a summary or procedure module can be used in a number of different places, as specified in your information architecture. The entire document can also be a module that is part of a larger set.
The modular design makes it easier for users to navigate through content—Well-designed modules have clearly-defined purposes and substantive labels, helping users to find their way to the right content.
Modular units of content can be isolated and updated quickly and easily—Modules can be accessed apart from the document as a whole.
Modularity allows you to rearrange units as required—Reusable content helps you accommodate different users’ needs or different publications’ needs.

Modular writing requires defining what your modules are, describing how they are structured and how to write them. Modules must be consistent to support content reuse so that reuse is transparent to your users.

Want to learn more about reuse?Read part two of this article.

About the Author
Pamela Kostur is a partner in Parallax Communications, a full-service communications consulting company in Toronto, Canada. With a focus on content and writing, Parallax specializes in content management strategies, structured writing, corporate and marketing communications, technical communication, and content development.

Kostur has authored several articles and taught workshops on topics such as miscommunication, usability, content management, information architecture, content modeling, writing for reuse, and structured writing. She is also a co-author of the best-selling Managing Enterprise Content: A Unified Content Strategy (New Riders, 2002).

Learn more about Writing for Reuse at Pamela’s upcoming workshops at DocTrain Life Sciences in Indianapolis, IN, June 23-26, 2008. Contact Pamela via email or phone—+1 416.850.0636.

Filed under: Content Reuse : DITA : Lessons Learned : Structured Content : Technical Writing : Structured Authoring

Comments

By Merle Tenney on June 16, 2008 -- 1:59pm

Thanks, Pamela, for a good overview of HOW to write content for reuse. I find it amazing that the great work that is being put in on developing DITA, CCM, and other reusable content systems is not matched by thoughtful guidance on how to make it all work. You are filling an important void, Pamela. Thanks.

For those of you who are new to Pamela’s work or long-time fans, you may be interested in a very useful slide deck on Writing for Reuse that Pamela posted on slideshare.net. Here is the URL:

http://www.slideshare.net/abelsp/writing-for-reuse-learning-how-to-write-modular-content-for-reuse

I attended Pamela’s session on writing for reuse at the recent DocTrainWest, and I was surprised to see how much more useful, new information there is in the slide deck. In particular, she offers more examples of diverse reuse plans. She offers more examples of writing guidelines for the different elements in the reuse plan (which I find to be invaluable). And she adds guidance for chunking and metadata to account for differences that must be accommodated in different uses (target documents, users, preferences) of the “same” reusable content. This was a question that was raised at her DocTrainWest presentation, so I am delighted to see that she has addressed it so quickly and so competently.

In short, if you want to know HOW to make reusable content work, keep up to date with Pamela’s work in this area.

- Merle