Barker, Chapter 13: Using Graphics Effectively

Graphics are an important part of technical documentation.

1. Identify Needs for Graphics by Your Users
Graphics in technical documentation assist the user in using the program and working with it.

Use graphics to support the questions you believe your users may have:

Where is it?
Graphics can support users in locating menus and buttons they will be using. Screen shots are great images to assist in locating these menus and buttons, so the user can see exactly what it is being discussed in the writing. It is very important that graphics are clear and understandable to the user.

What is it?
Use graphics to help users understand concepts. This includes examples and metaphors. Examples include printouts, reports, and documents and should be clearly explained. Metaphors explain something to the user in a way that they already understand. Most metaphors are language-based, but images increase the understanding of the metaphor. For example, users understand that the word and image of a mailbox stands for email.

How do I do it?
Users appreciate step-by-step instructions when learning something for the first time, and graphics really help in their understanding. Flowcharts are effective graphics to achieve this.

Where am I?
Access indicators and progress indicators are appropriate graphics to show users where they are at in a manual or help system.

What's the big picture?
Some graphics you can use to show overviews of programs include overall program diagrams, menu maps, conceptual overviews, and a page showing how to use the manual.

2. Set Graphics Styles
Your graphic styles should be consistent throughout the entire document. In some cases, it may be best to reduce the complexity in some graphics to allow the user to focus on what is most important in the image. Having a thorough knowledge of your graphics preparation tools will help you when it comes time to select which styles you will use.

3. Revise and Edit
When revising graphics, consider these guidelines:

- Give your graphics a clear purpose;
- Titles: complex images often require titles for clarity;
- Callouts: use callouts judiciously; they are most effective when not overused;
- Placement: place graphics consistently and as near to the text that refers to them as possible;
- Rules: rules and lines should be used sparingly to help give the page structure;
- Size: not too big, not too little; crop to show pertinent details; surround with white space;
- Colors: colors should reflect the patterns of information in the text.

4. Revise for Typography
Arrange images according to the logical structure of the information they contain. Make important things larger, darker, more central, and sharper. Align related things--first things to the left, later things to the right.

Discussion
Describe operations in a way that helps the user do meaningful work. You can do this by:

- Showing how tools apply to the workplace;
- Showing the results of software operations: most commonly these show the screen that appears after the keyboard/mouse has been used;
- Presenting overviews to integrate software with workplace activities: this helps user understand how the manual has been designed to work;
- Suggesting functions and uses: this can give the users ideas about how the software can benefit them;
- Using metaphors to make the abstract concrete; people love metaphors because they help them relate something new to something they already understand.

Central Works Essay 31

Cross-Cultural Collaboration: Whose Culture Is It, Anyway?

Deborah S. Bosley wrote this essay in 1993. She had previously written many articles about collaborative work and considered herself very knowledgeable about all aspects of the subject. Then two of her international students taught her something new when they discussed some cross-cultural issues on their evaluation forms after working on a collaborative project. Cross-cultural collaboration is something she had never even thought about. At the time, there wasn't much research done on it. This article was written after this introduction to cross-cultural issues in collaboration. She believes it is still valid today.

Definitions and Caveats

The common belief is that everyone learns the same, no matter what their race or backgrounds. Research in multicultural communication shows that differences do exist.

Without taking into account the context of a person's culture, it is impossible to understand the problems they might face in a collaborative group.

Cultural Differences in Behavior

Euro-North American culture places emphasis on individuality. Competitiveness is taught to children rather than collaboration, like in many other cultures. The success and achievements of Euro-North Americans are measured individually, even in group settings. The idea is that this competitiveness increases the productivity of the group. Other cultures believe this causes problems and could decrease productivity. Euro-North Americans praise those who make their own decisions, while those in communalistic cultures, such as many Asian cultures, believe that it is disrespectful to put your decisions above those of the group.

There are differences in oral and written communication for members of different cultures. Examples of oral differences lie in the use of context, comfortableness with silence, and exaggeration. Written differences include the organization and structure of texts.

Strategies for Internationalizing Collaborative Groups

Groups should recognize and take into consideration any cross-cultural differences that lie within their group right from the beginning. Group members can learn from one another and learn to appreciate each member's strengths and differences. Every member can gain positive effects from cross-cultural communication.

Barker, Chapter 9: Editing and Fine Tuning

1. Establish Project Guidelines
Everyone involved should understand their roles for each project, as well as the team goals. A person may be a combined writer/editor, a writer, or an editor. The four types of editing that should be covered in a project are managerial editing, substantive editing, copyediting, and proofreading.

2. Understand the Types of Editing
Managerial editing: Sometimes called the production editing stage, this type of editing involves the documentation planning and production.

Substantive editing: Sometimes called the developmental editing stage, this type of editing involves information and language editing.

Copyediting: This type of editing involves consistency and accuracy in grammar and the document's format.

Proofreading: This type of editing involves giving everything a final look to make sure there are no inconsistencies or errors.

Note: When editing help documents, online testing and editing is important to ensure proper setup of the document on the computer.

3. Plan Your Editing Tasks
Plan and schedule the editing tasks in the early stages of production. Take into consideration the amount of time needed to complete each task when scheduling editing work. Make sure that when editing, no other tasks are performed. It is not the job of the editor to perform any of the writer's tasks, and it could back up the schedule if other tasks are worked on when they shouldn't be.

4. Develop the Appropriate Editing Forms
Develop and use editing forms to standardize editing practices and ensure efficient communication among multiple editors. Of particular importance is the style sheet (a running list of style decisions that have been made for the current document) and the style guide (a higher-level document that broadly defines the style of the document class or organization). Once these documents have been developed, encourage their use.

5. Conduct Editing Sessions
Sooner or later, you will sit down with the document and begin editing. Find an environment that maximizes your ability to concentrate. For most people, it must be absolutely quiet, with no disruptions. Use an editing checklist to make sure you don't skip any editing tasks--especially important when editing your own writing. Try editing with a partner--two brains are better than one. Also consider working on each task for only a short time. Your attention will be less likely to wander. Use multiple, separate editing techniques, rather than trying to catch everything on the first pass.

DISCUSSION

Editing Graphics
Figures and tables are often the first things a user will look at. The editor must ensure that the figures and tables are appropriate and accurate and that they match the document's style. Avoid cluttering screen shots with arrows and callouts--they distract when overused. Ask yourself, Will this figure help the user understand the information? Is there a better way? Know your audience.

Writing v. Editing
Writing and editing are completely separate tasks. If you are the writer and the editor, try to let the document cool off before you begin editing it. You'll need some distance to make unclouded decisions about your own work. If you are the editor of someone else's work, give them suggestions but avoid researching and writing for them.

Crossing Cultures
If your document will be read by non-native English speakers, try to make it easy on them by using simplified English. Simplified English stresses the active voice, the use of articles, the use of consistent language, and the construction of short, direct sentences. If the document will be globalized, used generic language that will be understandable across cultures. If your document will be localized, use language that is familiar to the culture the document is destined for.

When editing for translations, the rules for simplified English apply. In general, try to make it easy on the translator to render the text into a different language. This is complicated and requires specialized training and practice.

Editing Online Help
Editing online help systems is similar to editing paper documents, but there are some differences. Pay special attention to the index and links because these will be used heavily by the average user. Edit on paper and on screen because it is generally easier to edit on paper, but you need to see how the document works on screen as well. Make sure you have an up-to-date topics list so you can check the completeness of the help system.

Knowing What's Correct
Much of the time, you won't. Consult various authorities to arrive at a consensus opinion, then stick with it. Above all, ensure that your document achieves the document's goals.

Working with Others
1. Be Positive; Don't Be a Pain in the Neck
2. See #1.

Campbell, Chapter 6: How Do I Get Them to Read This?

Making a good first impression is important in order to draw readers in. Design can accomplish this. Keep in mind two things: simplicity and visual clarity. If the document appears to be easy to read, then it probably is. A reader isn't going to spend time reading a manual that doesn't look like it will be easy to read. Keep the design and format simple.

Twenty design elements should be followed when creating a document, including elements like font, spacing, margins, and white space. (See the Design Tip Sheet 6-1, page 223 for the complete list.) These design elements are effective because of the human brain and eye movement. Because the brain can only handle up to seven different items at one time, it is good to limit your documents to three different items, to make it easier on the reader. No matter what, don't go over seven items. Use the Rule of Three as your guide in document design. Eye movement follows four patterns, which help determine effective document design:

1. Line length: Readers comprehend about 40 characters per glance, so it makes sense visually to limit line length to 40 characters.

2. Words per second: The eye comprehends three or more words per second, so keep words simple and use headings and sections to enhance the message.

3. Words at a time: The eye comprehends two or more words at a time. Because the eye groups words together, the small words may get missed, so be careful of your wording. Write as precisely as possible, cutting down on descriptive words.

4. Zigzag reading pattern: The eye reads in a zigzag pattern, from top to bottom and left to right, so be cautious about emphasis and image placement to avoid the eye from going off of its normal reading track.

Chunk

The limitations of the brain and eye require that we "chunk" material on the page to aid in visual recognition. If we present the reader with too much information at once, the reader will probably not be excited to digest it all. If we chunk it, the reader is more likely to be receptive to what we have written. There are many ways to chunk (use short words, sentences, and paragraphs; headings; color; lists), the important thing is to do it.

Add White Space

Adding white space to a document gives the impression that the material can be read easily. This is a psychological effect on the reader and will result in a more usable document. Dense text on a page creates a gray appearance and reduces the ability of the reader to get through the material quickly. Opening up the document by adding white space draws the reader in and motivates them to read.

However, adding white space will increase the overall length of your document. Usually, the need for white space trumps the desire for a shorter document. If, however, the added white space will create a document that is too massive, you have only two options:

1. cram it all into one dense manual, or
2. split the material into two manuals with more white space.

Your decision will be based on the needs of your users.

Remember that too much white space can be just as bad as too little. Create a visually appealing balance by exercising restraint, discipline, and moderation.

Be Consistent
Forget the adage that "consistency is the hobgoblin of little minds." Be consistent in all aspects of your document design and writing. Consistency will reduce the effort needed by the reader to make sense of your document. Inconsistencies break the reader's rhythm--avoid this.

Team 4 (Chapman and Lukkonen)

Barker, Chapter 2: Writing to Teach — Tutorials

Tutorials are designed to teach how to use something, such as new software. It may teach a beginner focused lessons on starting out, or it may teach an advanced user more complex focused lessons. Tutorials, like other software documentation, should be created with the user in mind.

Guidelines

There are seven recommended guidelines to follow for tutorial design:

1. Identify User Actions You Need to Support

Analyze the users of the program and their needs, including what they use on the job, what software features are essential, and what features are used frequently. Embedded tutorials are useful to detect important skill lessons, but it should be clear how to close the embedded tutorial if not needed.

2. State Objectives as Real-World Performance

The objectives of the tutorial should be stated in the module in terms of the user's performance. State exactly what will be learned in measurable terms.

3. Choose the Right Type of Tutorial

Types of tutorials include The Guided Tour, The Demonstration, The Quick Start, The Guided Exploration, and The Instruction Manual. The Guided Tour consists of an overview of the main features of a program. It can be online or in print. The Demonstration demonstrates specific actions in a program. Experienced users may use The Quick Start to jump right in to a program and start working with it. The Guided Exploration allows the user to determine the direction of the tutorial, exploring its options. Finally, The Instruction Manual teaches users step by step how to use a program, from basic features to more advanced ones.

4. Present Skills in a Logical, Cumulative Structure

It is not enough to prepare logical and organized lessons in your tutorials--you must also order those lessons in a logical and coherent way. Like other aspects of documentation, the proper order and structure will be determined through an evaluation of your user's needs, i.e., a typical-use scenario. Usually, the tutorial will progress from the general to the specific, the structure of which will mirror the typical user's workplace routine.

5. Offer Highly Specific Instructions

Instructions should emphasize scenarios that are familiar and applicable to the user. These scenarios should contain specific instructions to ground the user in the lesson. Keeping them grounded will help them fight feelings of insecurity they may be having toward having to master a new tool. Some examples of specific instructions include using concrete data, interface tools, screens, and specific commands. In addition, remove all distractions from the lesson, including page design elements that may interfere with the learning process.

6. Give Practice and Feedback at Each Skill Level

Giving users positive feedback in a conversational and positive manner will help orient them emotionally to the tool you are helping them learn and to the tutorial itself. Avoiding jargon and making liberal use of "you" and "we" will give the tutorial a "human touch."

Building consistent patterns gives predictability to the tutorial and reduces the amount of work the user must go through to understand the concepts that are being taught. Avoid alternative explanations because they may overwhelm some users and distract them from what they are learning. If feasible, build in practice exercises or quizzes into the tutorial to help keep the interest of adults who enjoy challenges and self-exploration.

Because most of your users will have competing demands on their time, keep the lessons short, about 10 to 12 minutes each. Also, let them know how to save their progress in case they need to shut the tutorial down and pick up where they left off at a later time.

7. Test Your Tutorial

Usability testing gives you necessary information about the effectiveness of your tutorial. If possible, test the tutorial in a real user environment. Focus the testing on the design elements, such as the cuing system and graphics. Perhaps most important, ensure that users can complete the lessons in the allotted time and that the lessons result in real learning.

Designing Tutorials

Because tutorials are designed to teach, the tone of the writer's persona must match the intended user to create a close relationship between the two. Because the goal of tutorials is to internalize work-related tasks and concepts, try to limit the scope of what the user is exposed to. This contrasts with other forms of documentation in which the writer attempts to be as expansive as possible. In order to narrow the scope of the tutorial appropriately, you must fully understand the needs of the user--which tasks are essential to them and which aren't? Without a thorough user analysis, it is impossible to narrow the scope of the tutorial appropriately.

Tutorial Users Need Special Care

Most of your users will be adults who have their own motivations for wanting to learn the tool that your tutorial is helping them master. For your tutorial to help them successfully, you must take into account the varied learning styles of your target population. As a tutorial designer, you need to understand how to limit the lesson times, prevent the user from being publicly humiliated for mistakes they make, give positive feedback, and make the user feel that they are self-directing their own learning.

Two Trends in Tutorial Design: Elaborative and Minimalist

The elaborative approach to tutorial design emphasizes reiteration to "bring the message home" to the user. Summaries, examples, and explanations all reiterate the learned material and may help the user retain and apply the knowledge they have gained. This approach is especially important for novice users with little-to-no experience with computers or the program being taught.The minimalist approach gives a nod to real human behavior: people often want to get off and running, without spending a lot of time in advance preparation. In the minimalist approach, the introductions and summaries are discarded because most readers will skip them anyway. To create effective minimalist documentation, use an action-oriented approach that is grounded in a workplace context that helps users recover from errors made and supports reading to "do, study, and locate."

Team 4 (Chapman and Lukkonen)