Information
Developer's Toolkit:
How to Write Information So You Can Use It Again
models | processes
techniques | links
resources
on i.d. business and management
home
|
Information
Developer's Toolkit:
|
models | processes |
In this Article |
Consider this.. You have written a user’s manual for Microsoft Word for Windows. Now you have been asked to write a user’s manual for Microsoft Word for the Macintosh. The two word processors are essentially the same; the primary differences emerge from the differences between Windows and Macintosh systems. You feel that you should be able to prepare the second manual in next to no time, because you can essentially use the information you wrote for the Word for Windows manual again, with some technical changes.
This is an example of re-using information and it is a common task among technical communicators. We reuse information for many reasons:
As the demand for information grows faster than the availability of people to develop that information, technical communicators are showing increasing interest in reusing information.
In an ideal situation, information can be used "as is," with no changes. But in most situations, the information cannot be used as is because
The next several sections describe issues you need to consider when reusing information:
The experts in fashion suggest that if you have a limited budget, you buy a few "classic" items that are almost always in fashion and simply change the accessories. Each year, then, rather than buying an entirely new wardrobe, you simply need to buy a few new accessories that make the classic basics look brand new. For example, a blue blazer, gray slacks, and a white shirt are as classic as fashion gets. By changing the tie, the belt, and the buttons on the blazer, you can create an entirely new outfit from the same clothes.
In the same manner, if you are working with some "classic" information that will be used over and over again in a number of different places within a technical communication product or in a number of communication products, you can prepare the information once and "accessorize" it, so to speak, each time you Reuse it.
For example, imagine that you are preparing the marketing literature for a large training organization. Although each department offers different courses, the following information is the same, no matter which set of courses you are describing: the general description of the organization, enrollment instructions, and the location of training center. So, you could write this basic information once, then Reuse it in the brochures produced by each department. You could use it again in a course catalog used to promote all of the courses offered by the organization.
These chunks of re-usable information are called modules.
Re-usable modules are most commonly used in these instances:
The schedule for producing proposals is usually tight; by writing this information once and re-using it, you can expend your energies writing other information that addresses a client’s requests that are specific to a project.
Often, models operate similarly. So, rather than develop an entirely new set of communication products for each model, organizations prefer to develop one basic set of products, then tailor it for the different models and markets.
When you create a module of text, consider the following suggestions:
Much technical information is revised and published again or reused. For example, most computer software is regularly updated and the manuals that describe the software are also updated.
According to Levine, Pesante, and Dunkle (1991), documents are like software in that entire parts of documents¾ from phrases to entire chapters¾ can be reused for new purposes either in part or in whole.
By considering that information might be reused when you write it, you can simplify the process of revising and re-using the information. According to Holden (1983), you can minimize the cost and effort of later reuse by writing generically. This means, you avoid unnecessary details when possible, such as names, numbers, and cross-references. Consider this example. Instead of writing "the following three items," you might write "the following items" so if the list of items expands to four when the document is revised, the lead-in to the list does not need to be revised.
In most instances, writing generically does not hinder the reading process. In many instances, writing generically might even help users by keeping them focused on the key details rather than trivial ones.
Write generically whenever a document might be revised or reused. Usually you are told that a document might be revised. In other instances, you can make educated guesses. For example, information about software is almost always revised. Sales information is often revised with the introduction of new or changed products. You can anticipate when a document might be reused by understanding the information needs of your organization.
Writing generically offers these benefits:
Writing generically involves questioning whether details are necessary or not. Every time you begin to write a specific detail ask whether it is necessary.
Here are some ways to avoid unnecessary detail:
The system has three elements
Say:
The system has these elements
At the next revision, the system might have been simplified so it only has two items.
If you are using all of the models--models 1, 2, and 3
Say:
Whatever model you use
At the next revision, model 2 might be discontinued and a model 4 might be added.
Chapter 6
Say:
Installing the System
In a future edition, this chapter might become chapter 2.
Consider these examples of writing generically.
You need not always write generically. Consider the statement: "Sign all five parts of the insurance agreement or the agreement is not considered valid." Five is a significant detail in this sentence. If readers do not sign all five parts of the agreement, they face serious consequences.
Similarly, consider the statement: "Autostart is only available on Model B33." The model number is a significant detail because autostart is only available on that model.
Sometimes, the information you want to use again has already been written by someone else. In such instances, you can use the information again....
....if you receive permission.
The manner in which you ask for permission varies, depending on what you want to use and how much.
| If You Want to Use | You Must Do the Following Before You Can Reuse the Material |
| Material published by your organization (or a division of your organization) and the organization owns the copyright of the material you want to use¾ and of the information product you are producing | Use the material as is. In the eyes of the law, the author is the same. |
| Material that you wrote yourself before, but for which someone else holds the copyright and you are now working for another organization | Request permission to create a "derivative work." Even though you wrote the information, you do not own it; the organization for whom you wrote it does. Therefore, you do not have the rights to use the material again without permission. |
| A single quote of less than 250 words of text from a single source or 4 or fewer quotes averaging less than 150 words each | Cite the source, just as you would do if you were writing a term paper in school. No additional permission is needed. When citing a work, you indicate the author, the work, the year, the publisher, and the page from which you took the citation. |
| A single quote or more than 250 words of text from a single source or 4 or more quotes averaging 150 or more words each | Write to the organization owning the copyright. (Check the
copyright notice in the communication product. In most instances, the publisher, rather
than the author, owns the copyright.) The owner will likely charge you a fee for using the
material. In many instances, the fee will be nominal (less than $50 US). But fees can
range much higher than that. If the owner of the copyright does not respond to your request, try again. You should try at least three times to reach the owner to demonstrate that you made a "good faith effort" to obtain permission. Keep copies of the letters so, if the holder of the copyright challenges you, you can demonstrate that you made an good faith effort. |
| Clip art, photographs from a stock photo CD, and stock sound | Check the information provided with the clip art package or the stock photo CD to make sure that you can use it without permission. In some cases, you may have to pay a fee, even if you are using clip art or a stock image. When in doubt, check with the publisher. |
| Other illustrations and photographs, illustrations (even if you adapt the material or change the medium, such as a screen capture from a commercial product), and other music, especially popular music | Request permission from the owner of the copyright. This includes images made available on the Internet or in another electronic source. Be prepared to pay a fee for use of the photograph or illustration. Fees are usually set by the medium and the anticipated number of viewers. Fees for and illustrations photographs typically run $500 US or higher. Fees for popular songs are similarly high. Permission for some songs, such as those by the Beatles, are generally not granted. |
Note, however, that you do not always need to request permission to use information. Some material is exempted from copyright laws. This includes:
When in doubt, however, seek permission.
models | processes | techniques | resources on i.d. business and management | home
(c) Copyright. 1999, 2000, 2001, 2002. Saul Carliner. All rights reserved.