Barker Chapter 12: Getting the Language Right

An important method in writing software manuals is to do so in a way that is performance-oriented.

Guidelines

There are five guidelines Barker writes about regarding user-oriented style:

1. Write about actions rather than functions.
   Structure the language to support the resulting actions of functions. Identify the function and then explain what the user can do with it. The more you focus on usefulness rather than on functions, the more the user will realize that usefulness.


2. Revise for the active voice.
   Revise statements to include active voice. See Table 12.1 on page 386 for examples.


3. Revise to keep writing simple
   Simplicity helps every aspect of manual writing. Avoid extra filler and similar unnecessary information. Keep the subject and verb together.


4. Revise to build parallel structures
   Consider parallelism (for example, consistently using the same grammatical structure such as verb ending ing in headings) as consistency keeps a document's content from becoming confusing. Check Table 12.2 on page 388 for examples.


5. Add operational overviews
   Providing overviews cuts down on confusion for users who may not be completely familiar with the material. Tell them how the program benefits them. "Your manual is like a bathroom key: People want to get their hands on it not because of its intrinsic properties but because it lets them do what they need to do" (389). Writers primarily use three ways to emphasize explanations of abstract concepts: "the theoretical (emphasizing the theories behind the working of the program), the technical (emphasizing the technical functioning of the program), and the operational (empasizing the application of the program)" (389). Check Table 12.3 on page 390 for more details.

Discussion

"In software documentation, you will often use different writing styles and different tones to support different user tasks" (390). So,

How Do We Process Language?

First, you need to write words in a way that connects with the user. Information needs to be significant to them.

Users have specific searching behavior or problem-solving strategies, so the document information should appropriate the energy the user puts into specific tasks. The amount of meaning a text has depends on the user's task.

Performance-Oriented Language

Slow read-through rarely pays off. To avoid this problem, the software manual writer should use

• active voice.
• the pronoun you to make the text interactive.
• imperative verbs to trigger actions.
• real language (language that the reader can actually understand and learn from rather than formal language).

How Do We Remember and Learn

Users need to remember ideas they read in order to learn. Try to make connections with the user's memory; this will trigger those memories and will make learning easier.

Structured Sentences

Thorough knowledge of how to structure information clearly in sentences is essential for retention. Sentences should be simple and short.

Style Problems in Software Documentation

Styles issues such as too many abstractions, little performance support, and overly complex syntax will make your information difficult to use (See Table 12.4 on page 393 for more details).

Acronyms

Acronyms can make complex systems easier to define; however, overusing them is not recommended. They will show up, though as software systems often contain hundreds of them. They also can save a lot of time.

Synonyms

Synonyms should be used consistently but carefully as they may be similar, but can evoke different meanings. One option to consider regarding this is indexing.

Paragraphs and Sentences Too Long

Paragraphs should focus on explanations, not performance, and not on steps telling the reader what to do. They work best when they support a simple concept. "They help explain what happens after a step, and, because the user will not usually tackle paragraphs unless he or she must, they shuld read as quickly and easily as possible" (395).

Emphasizing the Computer Instead of the Program

Since the user interacts with the program rather than the computer, you should create information that focuses on working with the software.

No Connection Between the Heading and the Topic

Headings must be meaningful, and the topic following should support that information. Specific explanations are usually all that's needed.

Too Formal Tone

Make software documentation conversational, not too formal. Sentences are meant to connect with another real person. Speaking in an informal tone makes contact more quickly and evokes the user's desire to do well on the job.

When to Use Humor

Avoid it. That's the impression I got from the reading.

Ambiguous Task Names

Avoid making vague references. "In task-oriented documentation you should name tasks clearly, with a sense of planning for the user's new vocabulary" (398). The name of the task should appear frequently in the text of the manual.

Step Not a Step

Examine youre steps to make sure they contain a clearly stated action, often using an imperative verb.

Thanks! Team 3 (Carlson and Hood)

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.