Information
Designer's Toolkit
Preparing Descriptions
models | processes
techniques | links
resources
on i.d. business and management
home
|
Information
Designer's Toolkit
|
models | processes |
A description"sets the stage" (Brusaw, Alred, Oliu, 1976, p.163). It is a type of passage that presents a concept to an audience. The "concept" might be something tangible, like a new computer or a new building, or it might be something abstract, like a proposed re-organization of a business or a proposed new accounting policy.
In some ways, descriptions are like tutorials, in that they teach something new to an audience. Because the audience often does not have an opportunity to try out the information and is not tested on their mastery of the knowledge as would happen in a formal tutorial, a description is less formal than a tutorial.
Descriptions have three parts:
To gain readers' attention, consider using one of the following:
State the main and supporting points in observable and measurable terms. You do this so you can objectively assess whether readers "got it" or not. For example, you cannot observe whether someone "knows" something or "understands it," but you can observe whether someone can "name key features" or "describe the 4 reasons that…"
For more information on writing main and supporting points in observable and measurable terms, click here.
Although the structure of a description is dictated by the supporting points (one main section for each supporting point), you have tremendous flexibility and creativity in the way you present those points. Some of the approaches (but certainly not all) include explanations, examples, and analogies.
Writing Explanations: An explanation calls attention to key characteristics of the subject it describes. The strength of an explanation lies in its ability to concretely identify and present these characteristics. Following the characteristics of a good technical writing style (as described in Style-o-Rama) helps you keep explanations clear.
Following is an explanation of a monthly activity report:
A monthly activity report is intended for your manager and includes a list of all major activities you performed during the month. Major activities include progress on assigned projects, regularly assigned duties, and special projects handled during the month. Monthly activity reports should also include an account of all training received during the month. Your manager compiles information from each employee's monthly activity report to develop a monthly activity report for the entire department. Monthly activity reports are due the second business day of the following month.
Notice that the explanation presents the key features of the monthly activity report as well as its intended audience and deadline.
Following is a poor explanation of the term monthly activity report:
A report you turn in to your boss at the end of the month explaining your activities for the month.
Although the explanation tells you the main content of the report and its primary audience, the explanation fails to:
Writing Analogies: An analogy is a comparison that relates an unfamiliar concept to a familiar one and explains what the similarity is. An analogy can provide "a shortcut means of communication if it is used with care" (Brusaw, Alred, and Oliu, 1976, p. 37).
As noted earlier in this book, users best understand new information when you present it in terms of something they already know. Users "attach" the new information to information already stored in memory. Users easily store and retrieve the new information. As a result, users are more likely to retain and use the information.
Analogies are especially useful for helping users "attach" new information to information they already know because analogies make unfamiliar concepts familiar and tell readers exactly how to store the new information. The better you understand your users, the more relevant the analogies you can choose.
According to Newby and Stepich (1990), you write analogies using the following formula.
| SOMETHING OLD | is like | SOMETHING NEW | QUALIFIER |
| subject | connector | analog | ground |
| Online information | is like | a book | in that both information contain information. |
Note the "ground" in the formula. The ground explains how the two concepts are similar. The use of a ground distinguishes analogies in technical communication from those in fiction, which merely state the comparison. As Newby and Stepich also suggest, you should use a visual to reinforce analogies when appropriate.
Examples of analogies include:
A computer file is like a file folder in that both hold information
(subject=computer file, analog=file fold, ground=both hold information).
A person's short-term memory is like a computer's random access memory in that it is an intermediate stop in the flow of information to long term storage and has a limited capacity
(subject=person's short-term memory, analog=computer's random access memory, ground=an intermediate stop . . . ).
A professional organization is like a trade guild in that it is an organization for people with similar job skills.
(subject=professional organization, analog=trade guild, ground=organization for people with similar job skills).
Webcasting is like television in that you see a picture and hear sound as it is being sent from the studio. But you receive the webcast on a PC rather than a TV and turn to a website rather than choosing a channel.
(subject=webcasting, analog=broadcasting, ground=see a picture and hear sound, ground= but you receive the webcast on a PC)
Writing Examples: An example illustrates a concept in real-world terms and provide users with an image of a concept that they can relate to.
For example, when describing how to enter a the DOS command DIR (directory),
Immediately follow the command with the name of a subdirectory.
DIR \subdirectory-name
Someone who has never used a subdirectory name might have difficulty understanding the previous passage, so the examples make the point clearer. For example, to display the contents of the subdirectory named work, enter
DIR \WORK
Closely related to examples are non-examples. According to Horn (1983), a non-example is something that might be confused with the concept you are trying to explain because the non-example is similar to the concept. The non-example, however, does not have all the distinguishing features.
Consider that frozen yogurt is a non-example of ice cream. Aspertame is a non-example of sugar. As examples benefit users by making the abstract clear, non-examples benefit users by clearing up possible confusion.
And confusion is the criterion to consider when determining whether you should provide examples. Use examples whenever you expect confusion. The confusion might result from a lack of clarity. For instance, you might include an example when describing an abstract concept.
The confusion might also result from similarity with other concepts. In these instances, you use both examples and non-examples to help readers determine which examples are instances of the concept and which ones are not.
Consider the similarities among ball-point and roller pens. They seem to be similar to the average person but use a different type of ink and a different type of point on the pen.
Carefully select examples to be representative of the types of situations users will encounter in their own work. For instance, when providing examples of identification numbers in the United States, you might use social security numbers. But these numbers are meaningless in Britain, which has its own system with its own name and own numbering scheme.
You should carefully select non-examples, too. Non-example should be as closely related to the example as possible so that users encounter the potential confusion and know how to differentiate it. For each non-example, explain why it is not an example. For instance, frozen yogurt is an ideal non-example for ice cream because it looks and tastes similar to ice cream but is made through a different process.
For guidance in writing a descriptive summary, click here.
When providing users with references to additional information, provide as complete information as possible, so users can most easily locate the reference. Specifically:
Follow this link to an article that explains what wizards are (the electronic ones, not the magicians).
models | processes | techniques | resources on i.d. business and management | home
(c) Copyright. 1999, 2000, 2001, 2002. Saul Carliner. All rights reserved.