Design is an integral part of any document and can improve or impair the reader's ability to find and comprehend information. In this module, we'll explore the different elements of document design and how to incorporate them into an effective, consistent layout that enhances readability and usability.
Technical information is communicated visually through graphics. We'll look in this module at the different types of graphics, factors for selecting graphics, and integrating text and graphics.
In a technical environment, we encounter situations in which we must explain to others how to do something, how an object is put together, or what happens during an activity. These situations call for special types of technical writing, instructions and technical descriptions. Instructions tell readers how to perform a task. Technical descriptions explain to readers how an object is assembled and operates or what happens in a process. We'll examine these types of technical writing in this module.
After completing this module, you should be able to:
design documents that serve their purpose and that are appropriate for the audience
describe the design elements that contribute to a pleasing, clear, usable document
identify various types of graphics appropriate for technical documents
integrate text and graphics effectively into a unified presentation
plan and write effective instructions that allow readers to complete an activity
develop clearly separated procedural steps that are logically organized, that are written in the imperative mood, and that follow a parallel, sequential structure
describe an object or explain a process using the appropriate level of technical detail, definitions, and partitioning that is effective for the audience and the purpose
We are surrounded by visual images vying for our attention. We are usually drawn to items with colorful packaging and visual appeal. The visual appeal of a document—its use of color, its title, its use of type fonts and sizes, and so on—invite us to take a closer look. The design of a document—the arrangement of its visual elements—encourages readers to examine the document more thoroughly and helps them find and comprehend information quickly and easily. Effective document design is of particular value in enhancing the readability and usability of technical documents. It guides readers to the information they need, emphasizes important information, and projects a positive image, thus reinforcing the message of the text.
Your document design should meet your purpose and your audience's needs. For instance, you can direct your readers to specific information within a section of a document by using a consistent system of headings and headers at the top of each page.
Chapter 13 of Markel and unit 7 of the course guide survey design concepts and elements and the ways in which they can help you achieve an effective document design. As you read these sections, look at the illustrations of the various design elements, such as page grids, typography, headings, and methods for accessing, emphasizing, and organizing information. These illustrations show how the design elements work together to visually signal the organization of information. This visual organization structure of a document helps readers find and understand information.
As you read chapter 13, consider these principles of page design: balance, consistency, and simplicity. Balance is the equal interaction of the elements on the page so that it is pleasing to the eye. Consistency refers to use of the same patterns on a page. Simplicity refers to not cluttering the page with too many elements. Keep the design simple and clean. Markel discusses these principles in greater detail.
Pay particular attention to the "Learning Theory and Its Relation to Page Design" section in Markel's chapter 13 (339). It presents three important principles of learning theory—chunking, queuing, and filtering—that will help you design effective documents.
Chunking, or presenting information in small units, is an important principle to apply to your document design. It helps your readers more easily comprehend the information. You can use chunking to separate independent units of information as well as to group related information. For example, suppose you need to explain a long, complex new personnel policy. Here are some tools used in chunking that you might consider to avoid glazed eyes and foggy minds among your readers:
typography: type families, point sizes, and attributes such as bolding and italics
page grids: columns and white space
methods of emphasizing information: short paragraphs, lists, and graphics
methods of enhancing information access: headings, tables of contents, and indexes
You can apply chunking to all levels of your document, from sentences to paragraphs to entire sections.
Queuing means arranging information chunks in a pattern indicating their level of importance. You may think of queuing as the visual hierarchy of information. An example of queuing is the different levels of headings used in a document. In this module, for instance, you recognize overview, objectives, and commentary as first-level headings. Within the commentary section, you see these subheadings, or second-level headings: Designing Documents, Using Graphics, Developing Instructions, and Developing Technical Descriptions. These headings create a visual pattern showing you how the information in the module is arranged.
Filtering is the identification of various types of information within a document so readers can find what they need. Examples of filtering are the use of icons to indicate specific types of information, such as overviews, in a user manual or a defined style for a heading that indicates a summary at the beginning of each section of a report. You can use filtering to direct different groups of readers to specific information in a document.
You can see numerous examples of graphics in technical documents. Some examples are
illustrations in technology-related articles in newspapers and general-interest magazines
diagrams of objects, materials, and equipment in repair manuals and instructions
graphs of stock market performance in financial documents
tables summarizing survey results in a report
Look around your office, home, or the Web and you'll likely find an example nearby.
Graphics in technical documents serve a variety of purposes, such as to summarize data, show how something works, depict relationships, compare and contrast variations in data, forecast trends, and increase reader interest. Graphics are especially beneficial to communicate hard-to-explain information such as how e-mail is transmitted, to describe abstract ideas to readers unfamiliar with them, and to explain information to multicultural audiences. Chapter 14 of Markel and unit 7 of the course guide discuss the reasons for and benefits of including graphics in a document.
When planning and selecting graphics for a document, consider your audience and purpose. Look at such factors as the readers' level of knowledge and interest in the topic and their expected use of the information.
For example, suppose you are preparing a report for your organization's management showing the costs of the information technology (IT) department's projects for the last six months. Management staff of both IT and financial departments will also use the report. What types of graphics can you use to illustrate the costs in this report? Here are three possibilities:
A pie chart to depict the percentages of different types of expenditures as an overview of the costs. This graphic will introduce readers to the projects on which IT spent money during this period.
A line graph to show trends in expenditures over the past six months. This graphic will help IT management determine trends in project expenditures and help them plan for the future.
A table to show detailed expenditures. This graphic will help financial department staff identify and verify IT's expenditures.
There are a variety of graphics—tables, pie charts, line and bar graphs, diagrams, and photographs to visually communicate your information. Chapter 14 of Markel describes the types of graphics and when to use them.
Text and graphics work together in a document to convey your message. Therefore, they should be integrated effectively to create a unified presentation. This need for integration may sound obvious, but often it isn't. Unit 7 of the course guide discusses guidelines for integrating graphics into text. There is a good example of effective text-graphics integration on pp. 7—21 to 7—24. Apply these guidelines whenever you are merging graphics and text in technical documents.
Next, we discuss two types of technical writing, instructions and technical descriptions, in which graphics and page design frequently play an important role in communicating the information.
Instructions tell readers how to complete a task. They are a particularly reader-oriented form of technical writing—that is, they are written from the readers' perspective. Good instructions not only inform readers how to do something but also persuade and encourage them to try a new, unfamiliar task and help project a positive image of your organization's products and services.
When planning a set of instructions, put your audience's needs first and foremost.Your audience is often people who are unfamiliar with the task. Your instructions may also be used by multiple audiences. To accommodate different groups of readers, organize and structure the instructions so that each group can find what it needs. Review the sections in unit 10 of the course guide about who uses instructions, and how, to help you plan them.
Task-oriented writing strategies help you achieve good reader-oriented instructions. These strategies include active voice, imperative mood (use of commands), present tense, precise language, and positive terminology. "Task-Oriented Writing Strategies" in unit 10 of the course guide presents examples illustrating these strategies. Pay particular attention to the use of the active voice and present tense in these examples.
Organizational writing structures help you arrange instructions effectively. There is chunking, of course, as well as lists; short, simple sentences; parallel structure; and clearly delineated steps. Two of these strategies, chunking and clearly delineated steps, are especially important in writing instructions. Begin each new major action as a separate numbered step. Think of the action as the start of a new chunk of information. Then present information related to this action, such as results.
By chunking information, you can present your steps in small units that makes it easier for readers to recognize and comprehend. A widely used modular design technique for chunking information has been developed by Information Mapping, Inc., consultants who help organizations integrate people, technology, and information. Unit 10 of the course guide briefly describes this technique. You can learn more about it from the description at the Information Mapping Europe Web site. You can then look at an example at the Information Mapping Web site.
Once you have developed instructions, you should test them for completeness, accuracy, and understandability. Usability testing is the process of conducting experiments with people who use the instructions to see how easily and accurately they can complete the task. The goals of this testing include developing safe and accurate products and services, increasing customer satisfaction, and reducing customer-support costs. Usability testing ranges from informal review and execution of your instructions by co-workers or customers to formal structured testing in a laboratory or real-world environment. The information on Usability Testing in chapter 3 of Markel (60-63) and the "Testing Instructions" section of unit 10 in the course guide present an excellent overview of the goals, concepts, preparation, conduct, and analysis of usability tests.
Chapter 20 in Markel and unit 10 of the course guide provide useful information about the following topics:
incorporating and emphasizing safety information in instructions
organizing instructions
testing instructions
examples of instructions
Technical descriptions explain how equipment, machines, or objects operate and are assembled and what happens during a process. A process can include an event, such as a hurricane, or an activity, such as the transmission of an e-mail message. Unit 9 of the course guide presents a variety of situations in which technical descriptions of objects or processes help readers learn more about them.
When describing an object or process, determine your purpose and analyze your audience's needs before beginning to write. The primary audience of technical descriptions is often people who are unfamiliar with the object or process. Use the questions about audience presented in Markel and unit 9 of the course guide to learn more about your readers. Your purpose and your readers' needs should guide you in selecting the level of technicality and detail to include in your technical description. In addition, look at the discussion about adapting your technical description to different audiences in unit 9 of the course guide.
The characteristics of a technical description help readers develop a mental image of an object or an understanding of the flow of a process. These characteristics are the language, use of active or passive voice, indicative mood, person, partitioning, and graphics. The language used in technical descriptions should be clear, specific, and concrete.
A technical description concentrates on the object or process. To help readers focus most on the topic, such descriptions are written in the third-person. When describing how an object is put together or a process occurs, select factual, verifiable information. Use the indicative mood for presenting facts, opinions, and questions.
Effective partitioning is important in a technical description. Similar to chunking, partitioning is the breaking down of the object into its components or the process into a series of smaller, related steps or stages. Partitioning can help readers understand how the object is constructed and operates or what happens during each step of a process. Technical descriptions should be organized according to the partitioning of the object or process. You can organize your object description into three patterns: spatial, chronological, or priority. Always organize a process explanation chronologically.
Graphics illustrate how the parts of an object fit together or the steps of a process occur. They are used in technical descriptions to illustrate an object and its parts, to summarize the flow of a process, and to explain abstract concepts. Graphics are especially beneficial for visually oriented or multicultural readers.
Unit 9 of the course guide provides details about the characteristics of technical descriptions. In the discussion about using active or passive voice on p. 9—29 of the course guide, compare the examples of active voice and passive voice. Notice the difference in the perspective.
Documents often combine technical descriptions with other types of technical writing, such as reports, proposals, manuals, or Web sites. Look at the examples of technical descriptions in the "Analyzing Some Descriptions" section of chapter 9 of Markel, and notice how they were adapted for different audiences and purposes.
This module has presented some insights into the design of documents and the creation of graphics, instructions, and technical descriptions.
In the next module, we shift our focus to another type of technical writing commonly used in technical environments: business letters, e-mail messages, and employment-related documents. With all the employment opportunities available for technical professionals today, being able to write these documents well can help you advance in your career and perhaps even increase the likelihood that you'll work in a more challenging and interesting position.