Barker - Chapter 13 - Using Graphics Effectively

Writing Software Documentation: A Task-Oriented Approach

Thomas T. Barker

Chapter 13 – Using Graphics Effectively

In this chapter, Barker explores on the use of illustrations in manuals and online help. He offers examines the role that images play in informing users, and presents guidelines for their effective use. This chapter also discusses the different types of graphical elements available and how they function.

Barker begins by presenting an example from a printed document and an online help screen that make use different types of graphics to deliver information.

Guidelines

Barker presents 4 guidelines for using graphics effectively.

1. Identify Needs for Graphics by Your Users

Barker asserts that graphics should serve to support two user questions: “How can I use the program easily?” and “How can I put the program to work?” That is to say, the graphics should help the user locate and act in order to efficiently operate the program, and they should also help the user understand, providing education, guidance, and support for workplace tasks. Graphics are not to be used as decoration, but as a way to explain concepts and illustrate examples. Revisit your user analysis, and think of ways in which graphics can help in meeting user needs.

Where Is It?

Graphics can serve to help users locate information in a number of ways. This includes:

• Show the user where to look to perform tasks
• Show concrete versions of abstract things
• Make visuals clear

What Is It?

Graphics can be used in various ways to help define concepts unfamiliar to the user. Users often require subject-matter knowledge or background information about a program or idea. Graphics can help provide this understanding through examples and metaphors.

Examples can show things like documents, reports, or printouts. This could also include showing sample data, all of which helps users identify the various aspects of a procedure. These often benefit from labels and explanatory text.

Metaphors involve illustrating an abstract concept by relating it to something the user already knows. Metaphors can help users to quickly grasp an idea without having to learn it from scratch. A prime example of this is the desktop metaphor used by many operating systems.

How Do I Do It?

Graphics can also be used to effectively demonstrate and support sequential actions. Graphics answer the question of “how?” by giving a visual overview of step-by-step procedures. A flowchart is a good example of this type of graphic. These help users to form a mental model of a process that they need to perform.

What’s the Big Picture?

Graphics can also be used to give users a broader understanding of a concept or process. Barker lists four forms that these illustrations may take:

• Overall Program Diagrams
• Menu Maps
• Conceptual Overviews
• How to Use the Manual

2. Set Graphics Styles

Just as you set styles for text, you should also use consistent styles when incorporating graphics into your document sets. Some of these stylistic elements include boxes and frames. These styles should be established early in the project, communicated to team members, and recorded in the documentation plan.

Barker lists several style elements that are of particular importance for graphics:

• Lines
• Fonts
• Arrow Styles
• Box Styles
• Frame Styles

In designing graphics, it’s also important to consider the degree of realism that you will utilize. All of these styles should be carefully documented in a table.

3. Revise and Edit

Once you have established standards, you should revise your illustrations based on those standards, in addition to overall correctness and consistency. Barker presents several points to keep in mind when revising graphics. “Graphics,” he states, “present the user with the thing itself rather than the word for the thing.” For this reason, graphics must be designed with a clear purpose. At the same time, it is important to recognize the value that words have in helping users to internalize a concept or process. This means that it is important to strike a balance between words and graphics when designing documents. Barker lists and discusses various aspects of documents that can incorporate or be augmented by graphics. These include:

• Titles
• Labels
• Placement
• Rules and Lines
• Size
• Colors

4. Revise for Typography

Typography refers to the arrangement of images based on a logical structure. Guidelines that can assist in achieving this are as follows:

• Make important things larger
• Make important things darker
• Make important things central
• Make important things sharper
• Align related things
• Put first things left, later things right

Discussion

“If a documenter has done the job well,” states Barker, “the user will not just press the correct key or button but do so in the context of meaningful work.” Graphics can help users to make clear connections between software operations and workplace actions by describing operations in meaningful ways.

Showing How Tools Apply to the Workplace

Illustrating the use of tools is directly related to the concept of task orientation. In some ways, it is the simplest form of instruction. You can support operation of interface elements (the “tools” of the program) by using images of the actions taking place, or illustrated tables of commands.

Show Results of Software Operations

Showing results occurs on all three levels of task orientation—teaching, guidance, and reference. An illustration of a tool combined with an illustration of the result of it’s use, work together to support the operation/result model of instruction.

Keys to Usability

Additional ways that illustrations can be used to support task oriented usability include:

• Presenting overviews to integrate software with workplace activities
• Suggesting functions and uses
• Making abstract concepts concrete through metaphors

Barker concludes with a glossary and checklist for incorporating and evaluating the use of graphics in a project.