Reuse Debugged

Posted on by Vimal

–Vandana Rao

The term reuse has several different connotations. In its most primitive form, reuse involves copying and pasting text. However, reuse is much more than just copying and pasting text. Reuse is essential in defining a unified content strategy; it can also help improve documentation processes and the quality of information products. Understanding different reuse methodologies and concepts and including reuse in documentation plans will enable you to define and set up an effective content reuse process.

Advantages of Reuse

The question of necessity of reuse, more so at the topic level, is easily answered today when resources are constantly under threat, budgets are under strain, and the onus is on developing more content with fewer writers: reuse enables you to manage more with less.

  • Efficiency: It is easy to copy and paste topics, but when you do need to update all of them, it will be time consuming and tedious. When you write for reuse, you only need to update once.
  • Consistency: Using the same content for manuals, guides, and online help ensures consistency across all the information products.
  • Modularity: Writing for reuse encourages modular writing. Information structured in modules is usable, and easy to identify and find.

Methods of Reuse

Reuse is generally categorized into two main types – opportunistic and planned.

Opportunistic reuse is a common method of reuse. Opportunistic reuse is ad hoc, unplanned, and incidental. For example, in the midst of developing content for a user manual, you find sections of the online help that already contains information that you need. A quick copy-paste helps you create new content for your guide.

Planned reuse, on the other hand, is methodical, conforms to pre-defined reuse guidelines, and goes a long way in providing a return on investment (ROI). In planned reuse, you explicitly identify reusable content (such as existing feature descriptions in guides that can be reused in online help), define strategies to reuse it, and write new content that can be reused in the future.

Opportunities for Reuse in Documentation

There are several different ways in which content may be reused. Most of these may be fairly obvious. The following list is by no means exhaustive, and is only indicative of the innumerable ways to achieve content reuse.

  • Template reuse
  • Outline reuse
  • Documentation reuse
  • Graphic reuse
  • Topic reuse

Even if you are writing for a documentation set where no planned reuse guidelines are in place, you will undoubtedly be familiar with the first four types of reuse just mentioned. Reusing documentation templates, outlines (such as reusing the table of contents of an existing installation guide to create an installation guide for a similar product), documents (in cases where products have similar components, each requiring documentation), graphics, images, and illustrations are all possibilities of reuse in documentation.

Topic, or even paragraph, reuse provides optimum advantages of reuse. Front matter, such as copyright notices, trademark information, document conventions are common examples of topics that can be reused across documents like installation, configuration, and user guides. Topic reuse can be extended to product overviews, architectural overviews, parameter definitions and so on, and applied across information products such as guides, online help, brochures, etc.

Reuse of templates and outlines help you in saving considerable time and effort. But these (templates and outlines) are a one-time effort within the documentation life cycle. In contrast, topic reuse is a continuous process, providing recurring ROI. Additionally, topics written for reuse are efficient, modular, usable, and consistent.

Topic reuse requires setting up a common reuse guideline that defines the principles for writing for reuse. If the planned reuse extends to a group of writers, topic reuse also requires the setting up of a collaboration plan.

Planning for Reuse

Reuse cannot just happen. Planning is essential to the success of reuse. When creating your documentation plan, ensure you include your content reuse plans.

  • Identify reusable components of your documentation set.
  • Understand that reuse has several connotations. Explore the various methods of reuse that are possible and identify the reuse methodology that works best for your documentation.
  • Explore possibilities of using the authoring tools features that help to automate reuse.
  • Define guidelines for writing for reuse.
  • Educate your writers about writing for reuse. Set up collaboration between writers and provide training. If you are moving from a setup where reuse was not formally supported to a reuse environment, writers need to learn to write for reuse.
  • Periodically review your reuse guidelines. Ensure that it is working as planned and that it continues to enable your documentation development process. Documents are live entities that need to change and adapt in order to be usable and useful to readers. Review your reuse processes to ensure that they are aiding the development process and not hindering them.

Reusable topics can be written and reused effectively if objective and tangible reuse guidelines are defined and applied systematically. Writing for reuse is not very much different from any other form of structured writing. It simply means that writers need to adhere to reuse guidelines in addition to style guides. Despite the fact that reuse appears to require additional effort on the part of the writer, the overall benefits of reuse outweigh the additional planning. Eventually, reuse not only helps in saving time and money, but helps writers write modular and usable topics.

References

Kostur, Pamela. 2008. How to Rewrite Content for Reuse: Part I. Retrieved October 15, 2009, fromhttp://www.dclab.com/reusable_content.asp

Ann Rockley, with Pamela Kostur and Steve Manning. 2002. Managing Enterprise Content: A Unified Content Strategy. New Rider Publishing. Chapter two, Fundamental Concepts of Reuse. Retrieved October 15, 2009, from http://www.managingenterprisecontent.com/

Will Tracz. 1990. Where Does Reuse Start? Retrieved October 15, 2009, fromhttp://delivery.acm.org/10.1145/390000/382702/p42-tracz.pdf?key1=382702&key2=5141105511&coll=portal&dl=ACM&CFID=15151515&CFTOKEN=6184618

About the Author

Vandana Rao (vandanasrao@yahoo.co.in) is a principal technical writer at BEA Systems (a wholly owned subsidiary of Oracle), prior to which she worked at Alcatel-Lucent and Terradune. With an interest in enhancing editing skills, she has recently enrolled in the Editing course at UC Berkeley Extension.