More than just discussing why reuse is valuable, in this article 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 exclusive article Pamela shows you how to plan an information architecture and move into developing structure and guidelines for a new reuse environment.

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.

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.(10 DITA Lessons Learned from Tech Writers in the Trenches.)

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.

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.

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 to 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.

Watch for Part II of How to Rewrite your Content for Reuse in an upcoming issue of DCLNews. Part II will focus on defining content modules, creating structure and guidelines for writers, and building a comprehensive reuse plan based on consistent, structured content.

DCLNews Editorial
March 2008