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.

Selfe & Selfe - The Politics of the Interface

The Politics of the Interface

Cynthia L. Selfe and Richard J. Selfe, Jr.

Introduction

The authors begin their article by recounting a story that was told to them by a colleague. Upon returning from a trip to Mexico, an Indian-born resident alien professor was detained at the border and eventually fined, since he did not have the required documentation to enter the country. The authors view this incident as an example of imperialism and unjustness, and use it as an analogy for the politics of computer interfaces. “It is at the geopolitical borders of countries,” state the authors, “that the formations of social power, normally hidden, are laid embarrassingly bare—where power in its rawest form is exercised.” They go on to state that teachers who use computers to teach English often contribute to the establishment and maintenance of these sorts of borders in their own classrooms, characterizing this activity as “the systematic domination and marginalization of…women, non-whites, and individuals who speak languages other than English.” In their article, the authors hope to describe the political and ideological boundaries associated with computer interfaces, ways in which these boundaries are constructed along ideological axes, how borders in computer interfaces can be mapped as complex political landscapes, ways in which borders can prevent the circulation of individuals for political purposes, ways in which students and teachers can learn to see and alter these borders in productive ways, and tactics that teachers can use to enact a radical pedagogy of electronic borders.

Computers as Learning Environments: History and Motivation

In this section, the authors begin by discussing the increase of computer technology within the field of English composition instruction. Computer-supported learning environments have generally been viewed optimistically by teachers, as “places within which teachers and students can try to enact educational practices that are more democratic and less systematically oppressive.” The authors quote research, however, that demonstrates that minority students and those of lower socioeconomic status remain a “technological underclass”, and are the least likely to gain computer skills during their public schooling. In order to face this reality, instructors are encouraged to become both technology users and technology critics, reflecting on the cultural and ideological characteristics of their technology.

Mapping the Interface of Computers as Educational Space

The authors acknowledge the ambitiousness of such a project, and declare that they will focus specifically on computer interfaces. They go on to describe interfaces as “cultural maps” of computer systems, maps that have ideological underpinnings. Like all maps, they reflect the historical and social values of the culture that produced them. “Primary computer interfaces,” they state, “do not…provide direct evidence of different cultures and races that make up the American social complex, nor do they show much evidence of different linguistic groups or groups of differing economic status.” Instead, the authors argue that these interfaces tend to exhibit the “monoculturalism, capitalism, and phallologic thinking” of “male, white, middle-class, professional cultures associated with the military-industrial complex.”

Interfaces as Maps of Capitalism and Class Privilege

The authors present examples of how these maps are exclusive, in that they based on a world that middle- and upper-class users know and are comfortable within. This includes using analogies such as the desktop, folders, files, documents, telephones, fax machines, clocks, watches, and calendars. They suggest that alternative icons could be used to represent different worlds, such as a kitchen countertop, a mechanic’s workbench, or a fast-food restaurant. They describe the white pointer hand in the Macintosh interface as a semiotic message about race. They also identify clipart collections as including images that are predominantly white, professional, and office-oriented. The authors also an association between computer use and capitalism, as more and more people are subscribing to internet service providers in order to access online information.

Interfaces as Maps of Discursive Privilege

Primary interfaces, the authors assert, tend to reproduce the privileged position of standard English as the default language of choice. Computer users must often pay extra to purchase versions of software that have been produced in other languages. Using English versions of software forces students from other races and cultures to “submit to the colonial power of language and adopt English.” The authors go on to describe the fundamental level at which many computer systems are based on English, so that even non-English speakers much make use of English symbols, such as those contained in the American Standard Code for Information Interchange (ASCII) character library.

Interfaces as Maps of Rationalism and Logocentric Privilege

In addition to the previously mentioned interface associations, the authors also believe these interfaces to be aligned with “values of rationality, hierarchy, and logocentrism characteristic of Western patriarchal cultures.” These values inform how information is represented and limit alternative possibilities. The article goes on to describe ways in which this hierarchical framework is actually limiting computer development. By incorporating methods of data representation such as “bricolage”, which refers to the construction of meaning through the arrangement and rearrangement of concrete materials in an intuitive rather than logical manner, the authors look forward to interfaces that exhibit the “epistemological pluralism” proposed by Turkle and Papert. Taken together, these interfaces “do violence to” minorities, imposing “a master narrative that resonates…with modern myths of technological progress.”

What to Do?

To respond to this phenomenon, the authors recommend that educators begin by locating themselves in relation to the map. Are we the cartographers creating the map, or the members of a dominant group that profits from it? We can then attempt to view the map from other vantage points to get a broader perspective. In this way, educators are better equipped to teach students how to view the interface “as an interested and partial map of our culture and as a linguistic contact zone that reveals power differentials.” Educators can also work with students and computer specialists to reimagine and redesign interfaces such that they avoid “disabling and devaluing” minorities. The article presents several tactics for accomplishing this.

Becoming Technology Critics as Well as Users

One tactic proposed for addressing this issue involves working to encourage a general level of critical awareness about technology issues among current teachers, and those planning to teach. As technological literacy and training is promoted within academia, it is important to also teach technological criticism, so that instructors think carefully about the implications of using technology in their classrooms.

Contributing to Technology Design

Humanist scholars and teachers should be involved in the practice of interface design. In some cases, this involvement can occur directly. However, since most instructors will not be directly involved in designing computer interfaces, they can influence the process by promoting collective professional action aimed at general technology design efforts. Online discussion forums can also be utilized in promoting this aim.

Reconceiving the Map of the Interface

Another strategy would be to involve composition teachers and students in a project to revise interfaces as texts. These projects can involve reconceiving interfaces according to a broad range of perspectives. New ideas for interfaces based on a range of “cultural, linguistic, and ideological perspectives” can be designed and expressed through either prose descriptions, drawings, or computer illustrations. This process could also include assembling libraries of icons and images that represent a diverse range of cultural values.

Toward a Critical Reading of Interfaces

The goal of eliminating oppression in our society represents a broad, ongoing challenge involving every aspect of life. For this reason, English teachers must work to bring these issues to light as they relate to computer interfaces. The article concludes with a quote from Winograd and Flores, who state that, having identified the ideological boundaries inherent in computer interfaces, we have a responsibility to “work towards unconcealment…and let our awareness guide our actions in creating and applying technology”.

Barker - Chapter 11 - Laying Out Pages and Screens

Writing Software Documentation: A Task-Oriented Approach

Thomas T. Barker

Chapter 11 – Laying Out Pages and Screens

This chapter describes two main elements of document design: the design of the screens and pages and the design of type. Barker begins by presenting several graphics illustrating major trends in page and screen design.

Guidelines

Barker’s 6 Guidelines for designing pages and screens proceed as follows:

1. Review the User Analysis

The goals of layout resemble those of document design in general. First, it’s designed to meet dynamic needs with a static document. Second, it should support overall task orientation. And third, it should accommodate the visual needs of the user, the need to learn and do through images rather than words.

2. Create Page Grids

Page grids define communication spaces by drawing invisible “fences” around areas of a page. They act like a scaffold or framework onto which text and graphics can be anchored.

These can incorporate design elements such as:

• Grid lines
• Margins
• Columns
• Gutters
• White space
• Baseline

3. Define the Page Grid Using Styles

The page grid defined in the last step should provide a road map for almost all your pages. At this point, you should define the styles that you want to use to set up the pages. This includes page elements such as margins, gutters, line spacing, the size and font of text, and so forth. Special concerns when designing for the screen include elements such as column spacing, arrangement of headings, and how hyperlinks are indicated.

4. Draw Thumbnail Sketches

A thumbnail sketch uses lines and spaces to show how pages should be organized. One method for producing these involves folding a piece of paper in half multiple times to produce a grid. At this point, you may draw in margins, columns, and page features. It helps to model your page design on a design you have seen that seems particularly suited to your project.

5. Set up Pages and Styles in Your Word Processor

Using a word processor or desktop publishing program, you can establish specifications for pages by defining both styles for text and page setup parameters. There are two very important reasons for using styles. These include:

• The styles can be changed later at a global level
• The styles ensure consistency across a document set

6. Determine the Layout of Help Documents

Screens offer an array of features you can use to create a usable and intuitive design. These include frames, narration strategies, hypertext links, and image maps. Remember that users search for information differently on a screen than on a page. It is important to understand the constraints of page and screen design, and how they differ. Barker presents a table listing some of the differences between page and screen layout elements.

Discussion

Designing Communication Spaces

There are two important aspects to any document that need to be decided:

• The degree of modularity pages and screens need
• The degree of structure pages and screens need

Modularity means breaking the information into chunks of text and graphic units to make them easier for the user to digest. Ask yourself if your page design contains all of the information needed by users to perform and fully understand the task. Barker quotes Edmond Weiss’ assertions that modules should be functional, independent, and small, providing greater ease of access that unlocks information. Online help documents can segment information more easily through the use of pop-up windows, expandable text, and rollovers.

Structure refers to the arrangement of information according to patterns. This requires defining spatial relationships between chunks of information. Research into how people process information has shown that individuals locate information in documents by remembering the physical location of information on the page. Elements that contribute to structure in a document include:

• Rules
• White space
• Bullets
• Chunks

Common Page Designs

In this section, Barker lists some common page designs. These include:

Two-Column Format: Allows the user to easily distinguish between guidance information and support information, and works best with procedures and step-by-step instruction. It is not as dense as a one-column format.

One-Column Format: This format keeps task information together in a linear form, and can be a good way to present long sections of prose.

The Elements of Page Design

In this section, Barker lists and discusses various elements that the document designer must consider in order to produce an effective document.

• The Left Margin
• Columns
• Headers and Footers
• Icons and Diagrams
• Screen Shots
• Rules
• Pagination

Barker concludes with examples of common page and screen designs, a glossary, and a document layout checklist.