Barker 14: Designing Indexes

Katy Mears
Erik Sorensen

Chapter 14 Barker: Designing Indexes

Two kinds of index methodology: manual or electronic
Chapter focuses on: what to index, levels of detail, phrasing, and techniques for building and proofreading.

1. Plan Your Indexing Strategy

A manual index requires you to go through the document and write index entries on cards or in a file. An electronic index uses the indexing feature of your software to make the index (437-438).

Manual Indexes: After finishing the document, write index entries down and alphabetize them. To determine index topics, follow these basic steps:
1. Review the user analysis to refresh yourself about the user’s needs.
2. Pick out terms/phrases that should be indexed. Look for: tables, figures, captions, main topics, important concepts, tool buttons, keyboard shortcuts, menu names, main tasks, examples and figures, definitions of terms, and acronyms or abbreviations.
3. Record the locations by page number
4. Alphabetize and edit the entries. Make sure all entries are consistent with formatting.

Electronic Indexes: Word processing software contains functions for indexing, often called “embedded indexing.” By identifying a term on the page and categorizing it, the program generates an index for you, as long as the entire document is in one file or a series of files. There are several advantages—automatic alphabetizing, automatic formatting, and ease of revision (ability to change entries at the last minute). The process is basically the same, with a few minor differences.
1. Review the user analysis to refresh yourself about the user’s needs.
2. Mark the index entries. Use the electronic marking feature of the software to determine the entries. You can do this as you are writing or editing.
3. Build the index. The software should automatically record and index entries and page numbers.
4. Edit the index. Check for inconsistencies such as double entries and missing entries. Edit the marked text not the index itself.

2. Decide What to Index

Many types of information can be indexed. Keep the user analysis in mind and you decide what types of information need to be indexed. The index should “support the activities and actions that the user will undertake in applying the program to workplace needs” (440). Make sure the documentation plan has specifications for indexing, if not, determine what they are and add them.

Index Categories:

Commands and Functions: Terms found on the menus. Format commands so they sound like parts of sentences.
Concepts: Ideas that are related to the subject matter. User must understand these to make the program work.
User Terms and Questions: Connect words the user knows to synonyms used in the program. For example, the software uses “quit” but the user may use “exit.”
Glossary Terms: Include a reference in the index for all the glossary terms.
Proper Names of Products and Companies: If your program writes files in formats usable by other programs or you refer to other companies you do business with, these should be included in the index.
Tasks and Procedures: A special index is sometimes needed for tasks and procedures. Tasks should be highlighted in a way that alerts the user to the guidance and step-by-step instructions.
3. Indentify the Level of Detail

Simple indexes have only one level and only show main headings. They are used for short documents. Two-level indexes organize terms by categories. Three or more levels make a complex index to organize many different types of information. See Table 14.1 for examples of the levels (444).
Light, medium, and heavy indexes show detail in another way. A light index has two to three items per page. A medium index has five to seven items per page. A heavy index has eight to nine items per page.


4. Decide on Phrasing and Format

You should spend some time planning for the phrasing and format of your index entries. There will be some issues such as being consistent in capitalization and bolding certain entries as opposed to others. Make sure to pay attention to special formatting of commands, tasks and functions.

5. Edit and Proofread

Once the index is created you should edit and proofread it for mistakes. Also make sure to pay attention to indents and page references to ensure their accuracy. Editing an index can take up to a 1/3 or the time devoted to creating an index. It’s important when editing to keep in mind the intended user’s characteristics.

Why an Index?

The index will express the overall organization of the document and puts the information in the user’s language. It provides direct access to the desired information. The index may even be put before the table of contents in some documents. The index also introduces the user to the vocabulary of the document.

Online Index vs. Print Index

Print Index – usually at the back of the book and divided by alphabet

Online Index – this type is often seen on websites. Allows scrolling of the index by selecting the letter.

Keyword Searches – Allows user to enter words in manually and then the search will determine the closest related topic. Usually focuses strictly on help topics.

Automatic Indexing Software Programs

There are a number of programs that exist that can create indexes automatically. The programs will do the majority of the examining and then organize information creating links to the topics. The user will still have control over the final product. Often the more exotic the indexing software, the more detailed an index can become.

Indexing with Search Engines

Often times indexing with search engines that examine the whole text provide results that have very little relevance to the desired outcome. To alleviate this problem, many search engines will filter out words that are determined to be useless. Because of the misspellings and other user errors many people have determined search engine indexing to create more work rather than lessen the work load.


Tools for Indexers

The American Society of Indexers (http://www.asindexing.org) lists a number of reference tools for indexers.

Other resources include:
· Dictionaries, thesauri and other language tools
· Encyclopedias, fact books
· Phone directories, geographical maps

Barker Chapter 13 Using Graphics Effectively

Graphics in manuals reinforce the key role images play in informing the user.

1.Identify needs for graphics by your users
Graphics should support user questions:
-How can I use the program easily? Use graphics to help user locate & act by providing images that educate, guide, and support workplace tasks.
-How can I put the program to work? Use graphics to help user understand by strategically placing them, helping to locate and direct
actions, explain concepts, and illustrate examples.

*Identify user questions then choose graphics to respond to user questions.

Where is it? Show user where to look to perform tasks: let the page reflect the screen; use capture and art programs to bring elements off the screen & into manuals & online help. Show concrete versions of abstract things: use images to emphasize important points & show how the program works. Make visuals clear: avoid clutter

What is it? Use graphics to define unfamiliar concepts to the user. Two types of graphics:
1) examples: show documents, reports, printouts, sample data. Explain & label graphics. Use examples liberally in high-tech, command-driven programs such as compilers, scientific graphing & analysis software & operating systems.
2) metaphors: show relation of ideas by relating to something familiar to user & allows users to rely on previous experience. Metaphors compare two things: the abstract & the concrete. Examples of metaphors: radio buttons, sliders, pull-down menus. Language metaphors are stronger if supported by the actual images suggested by the words.

How do I do it? Provide overviews of procedures introducing users to the steps that follow. Example of mental model: input-process-output.

Where am I? Access indicators show users their location in a manual or online help rather than tell them and keeps user from feeling lost. Examples of access indicators: diagrams showing current location in the process, history maps, header & footer icons. Progress indicators are helpful in tutorials so readers can easily see progress through the number of pages or lessons using headers or footers.

What’s the big picture? Users unfamiliar with computing or a new program need to know how it’s all put together (structured) since they cannot draw on previous experience. Experienced users may need reminders and expert users expect to have a structure in place. Keep things as small as possible when creating an overview graphic and use icons to make the connections between things seen on the screen and workplace demands. Color can be used for easy recognition. Some graphics elements to use:
Overall program diagrams: illustrate program system components to show the flow of information.
Menu maps: consist of program menus arranged on a page in the same structure they appear in the program interface; they help maintain as sense of organization of the program’s features.
Conceptual overviews: they reinforce the ideas of how to use a program; help users see how to employ the program in meaningful work through sharing information and resources. Guideline for designing conceptual overviews found on page 418.
How to use the manual: To determine what type of graphics to use to respond to user questions see Figure 13.13 on page 419.

2.Set graphics styles
Consistency is key! Use same types and fonts, same arrow styles, and box, and frame styles throughout your document. Table 13.3, page 421 lists elements of graphical styles. There may be advantages by deleting drawing details and using a cartoon or line drawing style since they help focus user attention on specific elements of a drawing. Photo realism in graphics uses more hard disc and CD storage space. Pre-planning is a good idea and the sooner you decide major issues such as size, type, graphic size, etc. the better.

3.Revise and edit
Once you’ve determined the kinds of graphics you’ll use, and have a working draft, you can revise for overall correctness and consistency. Watch for overcrowding, images, or text.

Guidelines for graphics revising:
Titles: Titles aren’t required on everything. Rule of thumb is the more complex, the more the need for a title. If user can’t easily see the relationship between the image and the text, add a title to clarify the image’s function. More guidelines page 423
Labels: Labels aren’t required for everything; they point out the salient elements of a picture or drawing and direct the user to the correct and informational parts. If you do label see page 423 for guidelines.
Placement: guidelines page 244
Size: guidelines page 244
Colors: guidelines page 245

4.Revise for typography
This means giving an arrangement to the images based on a logic. When using images, arrange and design to convey the meaning you intend. Guidelines: make important things larger, darker, central, and sharper, align related things, put first things left, later things right.

DISCUSSION:
Graphics make clear connections between software operations and workplace actions by:
• Showing how tools apply to the workplace
• Showing results of software operations
• Presenting overviews to integrate software with workplace activities
• Suggesting functions and uses: capture the typical-use scenario
• Making abstract concrete through the use of metaphors

Chapter 11 Barker: Getting the Language Right

This is just a comment on Barker's chapter 11, not the initial blog!
The concepts Barker writes about seem to follow the guidelines for all writing such as using active voice, keeping writing simple and geared to the user, and using the parallel structure. I thought he nailed it exactly with the idea that "A 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." Perfect. I look for exactly this in any manual. I want the information I need and the rest can wait until later, or never.
I learned about explaining abstract concepts when writing and, at my job, I usually use the operational concept that simply tells me what I need to know. I think AuthorIt might fall into the technical functioning of a program and that may be where I'm experiencing difficulties because I'm required to understand the technical aspects in order to perform what I need to do for the documentation project. I'm more interested in the productivity of AuthorIt than learning the technical parts. And that might be where the sticky part lies.
Understanding the different types of parallelism helps with all tutorial and instruction writing. Parallelism seems to work well in tutorials because it's based on action by the user and that is what our documentation and usability projects require in the quest to be user friendly and user helpful.

12 Campbell: We're Thinking About Going On-Line

12 Campbell: We're Thinking About Going On-Line
Team 2: Ender, Warren

What it means to go on-line
Going on-line is not a magic cure that will fix policy and procedure problems. It does not guarantee instant understanding or proper application. On-line documentations is just a different method of communicating information. In the past, users were bound by verbal or written information. Now there is also the option of sending information electronically.

Three methods of communicating with users
1. Verbal
2. Written
3. Electronic

What does not change
The content of your policies and procedures does not change. Neither does your writing, editing, or revision processes. All the challenges of good writing still exist.

What does change
The method by which the final policy or procedure is communicated to the user does change. Printing and copying is no longer necessary. Messages are sent on-line, rather than on paper.

Advantages of going on-line
• Logistical
⁃ lower maintenance costs
⁃ faster
⁃ more efficient
⁃ instant distribution of originals and revisions
⁃ space saving
⁃ easier access for disabled users
• Informational
⁃ can link related facts or documents together in a way that gives users faster access
⁃ can jump quickly from one document to another
• Motivational
⁃ less intimidating to users who are familiar with computers
⁃ easier and faster than picking up a 300 page manual

Disadvantages of going on-line
• Logistical
⁃ need for training
⁃ requires major organizational commitment of time, money, and resources
⁃ small screen size
⁃ higher initial costs for design and development
⁃ format limitations
⁃ lower readability
• Informational
⁃ fast access or ability to compare data can be hindered by inadequate software or hardware
⁃ format limitations tend to lend themselves to short documents
⁃ can encourage readers to skim or skip long documents
⁃ some users may not have access to a terminal
⁃ if the system crashes or is down for maintenance information is unavailable
• Motivational
⁃ peering at a screen is difficult and tedious
⁃ users may be intimidated by the system or by the computer
⁃ some users may prefer a hard copy


✓ Page 376: Questions to ask when going in-line externally


On-line design considerations
• Visual ease
⁃ use small blocks of text
⁃ limit the number of colors on the page to two
⁃ limit highlighting and other visual cues for emphasis
⁃ use simple graphics
⁃ use lots of white space
• Ease of use
⁃ use hypertext or searches
• Clear operating instructions
⁃ indicate page, document, or file size on the screen
⁃ differentiate between "page" and "screen"
⁃ use a "continued" notation at the bottom of text
⁃ create screen headers and footers, and be sure to keep them simple
⁃ if not using hypertext, include information on how to find related information

Designing an on-line system
Because of the limited readability of a computer screen, certain design considerations exist. Formats of an on-paper design would most likely be different than from an on-line design. Keep in mind that a computer screen is harder to see and concentrate on than a piece of paper. Try do eliminate visual clutter and keep the reader's attention.
Four design factors to keep in mind:
1. Visual simplicity
2. Ease of use
3. Clear operating instructions
4. Adequate conversion of elements

Chapter 11 Barker: Laying Out Pages and Screens

By Mary Dobbins

Guidelines for Designing Pages and Screens
1. Review the user analysis. Use typesize, fonts, etc. and design according to user types and experience, and users’ problem-solving techniques. Page and screen layout should support task orientation and lead users to the right kinds of information. Screens and icons should help the user make the connection between pages of the program.
2. Create the page grids. The grid is the framework onto which you put the text and graphics and contains: grid lines, margins, columns, gutters, white space, and baseline.
3. Define the page grid using styles. The grid provides the roadmap for your pages; then you have to identify the styles. Ideally, you should include all components listed in Table 11.1, Page 355.
4. Draw thumbnail sketches. Use sketches as part of your planning. Find an existing page that you like and then use it to follow the exercise on Page 356.
Tips: 1) Make sketches accurate, 2) Keep page items in proportion, 3) Keep shading and spaciousness close to the original.
5. Set up pages and styles in your word processor. This can be time-consuming but is important to ensure consistency in your document.
6. Determine the layout of help documents. Layout of pages and screens can differ which creates limitations. Table 11.2 on Page 360 compares data elements between pages and screens.

Designing Communication Spaces
Two important things need to be decided:
1. Degree of Modularity – breaking information into chunks of text and graphics. The modular format follows the one-task-per-page idea. Some helpful tips include:
- Repeat background information when necessary
- Repeat screens when necessary
- Include information about a related task
- Keep relevant steps together
- Minimize cross-references
2. Degree of Structure – placing information on the page according to patterns. Chunking is a technique that helps the user find information on the page. Structure includes:
- Rules – using different lengths and thicknesses to identify headings
- White space – helps to focus on graphics and creates balance
- Bullets – identifies organization of information easily
- Chunks – identifies related information

How to Look at Pages and Screens
Compare manuals for page density, balance (white vs. text space), and legibility (font and style). Common page designs include two-column format (graphics column and a text column) and a one-column format (graphics and text in the middle of the page). The two-column format works best for guidance-level documentation such as procedures or step-by-step instructions while the one-column format works best for procedures and reference manuals.

Contributing greatly to usability, the elements of page design include: the left margin, columns, headers and footers, icons and diagrams, screenshots, rules (border or artwork), and pagination.

Some tips when designing a screen include: forget line length since users can change the screen border and shape, avoid lots of scrolling because it’s disorienting, indicate another screen by using a “More” button or “1 of 3” indicator.

Multiple Windows Management
Be careful not to cover an entire screen when calling up an additional screen. Avoid using too many windows (window clutter). Make sure screens can be closed by the user.
Other helpful hints include using color to cue important elements, keep graphics simple, use screen grids (as described above), and in general, single spacing is best.

Helping People Recognize Words
People prefer visuals. Manuals that use visuals consistently test higher in usability. Be mindful of using words that could be confused with a look-a-like (disk vs. desk). Using a serif font works well for scanning because it helps the eye move quickly across the page. San serif works for large font size. Simplicity is best. More design advice:
- Choose a recognizable font
- Use a font that clearly shows the tails of the letters
- Choose a recognizable style
- Avoid long passages in italics or all caps
- Keep headings short
- Use serif for body text, sans serif for headings
Distinguish style of text for “hints, notes, or cautions” so that they are set apart of regular body text. Also, distinguish input or output messages (e.g., error messages) – courier new is often used.

Tables and Lists
Emphasize the headings so they are easy to recognize. The substance of the table or list should use the same style and font as the body text.

Chapter 11 - We Haven't Used That Procedure in Years

Team 7 Jaeger/Lopez

When to Revise a policy and procedure:

You must find a proper balance between:

1) Regularly scheduled review and revision

2) As-needed review and revision

The best balance for your organization depend both on content factors and on logisitics.

Regularly Scheduled Reviews:

Ideal time to review policies and procedures is once a year. Otherwise, create a realistic schedule that will work in your organization with your own time frames. The more frequent, the better. Consider your consequences if you choose not to review them. One method of reviewing is called rolling reviews. Roll through different groups of policies and procedures for review periodically and move along to the next, next time around. The key here is a disciplined schedule.

As-Needed Reviews:

A revision is needed when:

1) A significant number of changes have been made to the documents

2) Content changes, such as operation or legal, occur or are pending

3) Certain types of problems or behaviors increase

Accumulated Changes are when a number of changes have been made over a period of time to the policy and procedures document. You must eventually fix the whole and not continue to patch it up. Good rule to follow is if approximately 25% of a given policy or procedure has been changed, it’s time for a complete review.

Content Changes are when a policies and procedures need adjustment anytime you have new equipment, new programs, or new products, procedures, and policies. Makes notes on other people so opinions about your policies. Keep these for future changes.

Significant Clues might tell you that a change is necessary. Pay attention to others conversations and be alert at meetings; they could be telling you something. Some clues that it’s time for a change might include: Accidents, Errors, Complaints, Deviations, Questions, Rejection rates, Confusion, Corrective actions.

When Not to Revise

Even if your policy or procedure isn’t working, that might not mean it is time to review. Look at other reasons why it may not be working. Don’t rush to revision.

How Much to Revise

The goal is to change as much as necessary and as little as is possible. Depends. You can change: A portion of an individual policy or procedure, all of an individual policy or procedure, a section or related group of policies or procedures, an entire handbook or manual.

How to Revise

Research the topic, organize the information, format it, and draft it. Review it, edit it, and get it approved.

How to Clarify the Changes

Make it as easy as possible for the user to see what, and how much, has been revised by: Visually highlight the changes on the page, Use clear, descriptive wording in your transmittal document, and summarize the changes.

How to Hold Users Responsible

Revisions often have people saying afterward that “I never got it!” To avoid problems like this, use a notification system that forces users to share responsibility for updating their document(s). A shared responsibility system is fairly easy to construct.

1) 1) Users are given a revision index form on which they record all revision notices in the order or receipt.

2) 2) All change notices are clearly numbered in an obvious and easy to –identify manner.

3) 3) Users are instructed that it is their responsibility to record all change notices in their revision indexes and notify the appropriate person if any are missing.

4) 4) A summary of all the change notices issued is periodically sent to users.

This system is straightforward and simple, yet very effective.

Chatper 10 Campbell: But That's Not The Way We've Always Done It

Chapter 10 Campbell

But That’s Not the Way We’ve Always Done It

Don’t Give Up

You will undoubtedly run in to resistance and grief when trying to implement something new. All the user testing and ensuring there will be minimal problems is not all for nothing. Be patient.

Dealing with Resistance

Keep in mind that most resistance to change occurs because of fear. You will not be able eliminate other people’s fears but there are six things you can do to help users manage change:

Involve

Explain

Listen

Enforce

Reinforce

Evaluate

Early Communication

Initiating communication earlier on in the process will benefit you later. Early communication also serves two other critical purposes: Early detection and advanced preparation.

Early Detection

Skepticism is likely in the beginning. Most users think that the problem will go away or inevitably end up to their disadvantage. Open communication, as well as being honest in the beginning prevents problems in the end. Early detection will also reveal cynicism. Skepticism is one thing but cynicism can reveal a personal agenda. Communication in the beginning will help to reveal cynics.

Advance Preparation

Involving people early and often allows them to be included on the process and therefore allows them to be heard. Disagreements are still likely to occur but if the person feels they are genuinely being heard they are often easier to deal with.

Continuing Education

As implementation continues, keep talking to people. Run status updates by everyone even if nothing has happened. Keeping lines of communication open allows for continued input and allows for valuable opinions to be heard.

Final Notice

If you have kept communication lines open then the final notice of implementation will come as no surprise. Users who were heavily involved will make the transition smoothly. Make sure to keep listening to skeptics but also remember that there comes a time when you many need to put your foot down. Just be sure they understand the consequences of non-compliance.

Grace Periods

Grace periods allow for a gradual adjustment to a new system. The more controversial the policy or procedure the more grace period becomes vital. Grace periods allow for more preparation. Grace periods also let the user know that there is some flexibility initially and that full enforcement begins at a later date. Using a grace period is a sort of announced gradual transition that allows everyone to adapt gracefully.

Delivering Bad News

Don’t try to change an unpopular procedure to popular in a blink of an eye. Planning, patience and preparation are required. The greatest asset you have is the communication that has already taken place. If good communication has occurred than the user will likely trust you enough to listen seriously.

Preempting

Preempting is a way to deal with anticipated issues before they arise. Holding a meeting to discuss likely objections will steal the objectors thunder.

Taking the Heat

You must be willing to accept responsibility for the policies and procedures that you create. Just remember that people have the right to feel strongly about things that affect them or their jobs and it’s not personal. Be patient and calm.

Here Comes Trouble

There are 14 “indicators” for trouble (all 14 are located at the back of the chapter on page 339). Trouble is sometimes unavoidable with policies and procedures, but they are common ways to avoid problems. The most common indicators are:

Unfairness – Unfairness often really means “unreasonable from my point of view.” To avoid this, look at the policy from another’s point of view and make sure it is reasonable.

Negativity – Negativity is an unconscious trap during writing. It is easier to state “don’t do something” rather than an alternative. For example, instead of writing “don’t take extended breaks,” write “observe the scheduled break times.”

Hypocrisy – The substance of the policy must support the company’s goals and viewpoints. Actions that conflict with the words of a policy can be viewed as hypocritical.

Pointlessness – Point out why a policy or procedure is important. Workers are more willing to adapt to a policy that proves it will accomplish a task.

Unworkableness – There are three keys: accuracy, completeness, and testing. Make sure a policy can exist in the “real world” of the company.

Restrictiveness – Maintain a balance between control (policy and procedures) and flexibility (user’s needs). Be detailed when necessary, and specific when necessary.

When the Writer is the Resister

When writing a policy, you as the writer may not agree with it yourself. Be sure to address your own concerns the same way you would anyone else’s: listen and consider. Note the reasons for the policy and why it is being created and keep this in mind as you are writing it.

Chapter 10 Campbell: "But that's not the way we've always done it"

I can't resist blogging on this one! This chapter pointed out ways to work with negative feedback on any type of change. There is usually one person in my work group who is the first to say, 'it's a waste of time' to just about any change in policy or precedure. Even so, I've found that including the naysayers in every step of a process change goes a long way toward at least compliance at the end. The negative comments often do give me ideas I hadn't considered before and then can implement them in the change. Including everyone involved with the process goes a long way toward a better final product plus gives value to all input and this comes in handy for future changes or improvements. Everyone feels like their input matters, myself included, when users have a stake in the product. This is a way of demonstrating mutual respect too. Campbell's 6 steps to help users manage a change, involve, explain, listen, enforce, reinforce and evaluate, are going to be useful in my job in more areas than policy change. Campbell has a nice way of identifying and explaining things to remember when writing in general.

Chapter 10 - Barker - Designing for Task Orientation

Chapter 10 Barker -Designing for Task Orientation
By Team 6 – Owens

This chapter gives the technical writer the basics of book design and covers guidelines for designing to meet human user needs.

• Designing for Different Groups, consider your navigational aids, scenarios, icons, and metaphors
• Design for Specific Program Issues and include job performance aids, background information, special forms
• Meet the User’s Task Needs – by telling them how to do things rather than describing the terms and fields on the screen.
• Meet the User’s Information Needs – by understanding how information is used in the job setting and writing the help to let the user know how the program supports that work.
• Match the User’s Computer Experience – consider the predominant type of user whether novice, experienced or expert and tailor the help to that level of understanding.
• Enhance the User’s Subject-Matter Background – which will enhance the usability of the software, like adding a special glossary of background terms used by the user.
• Leverage the User’s Workplace – by getting help from co-workers or suggestions for support groups.
• Meet the User’s Learning Preferences – choosing the media and designing documents according to that media.
• Meet the User’s Usage Pattern – tailoring your software based on how the users will reference the document – regularly, casually, or strictly troubleshooting.

After deciding what design features you would like, you have to figure out what you can afford to have.

Online Help:

Designing for online help should parallel the process of designing for print. Identify and list the online help topics. Topics are defined as “an identifiable body of usable information associated with a user activity.” (p. 317). The user’s view the topics as the final destination because it provides information to get the user back to the task of making the program work.

Decide What Design Features to Use. Design features are the electronic interface elements of a help system. One of the main differences between print manuals and help lies in the umber of features available to you with the online media.

Accommodating Groups of Users:

You need to constantly consider the degrees of experience among groups of users as each will react differently. This means you have to write two or three manuals in one book. Two ways to group users are by degree of experience, or based on professional roles.

The experienced user is more patient with confidence in the program whereas the novice will blame the software.

Matching User’s Problem Solving Methods:

• No one carefully reads more than two sentences at a time, so based on that:
• Keep paragraphs short
• Arrange information into tables and lists wherever possible
• Put important information at the beginning of each paragraph.
• Most users begin to use the table of contents before they read the manual.
• Make the table of contents complete
• Use both an abbreviated and an elaborate table of contents for complex material
• Use chapter-by-chapter tables of contents
• Make table of contents headings task-oriented
• Most users go to the manual or help only after they have failed to perform a task
• Be sensitive to user’s state of mind after failure
• Make descriptions of error recovery clear and complete
• Emphasize getting back to real world tasks.
• Most readers do not read the introduction first
• Replace it with useful information about user needs
• Replace it with material designed to get them applying the program right away.
• Most readers do not read any section in its entirety
• Tell them which sections go for particular tasks
• Make sure all descriptions contain complete information for performing the task
• Repeat important information as necessary.
  

Design Guide for Printed Documentation:

• Use navigation aids
• Use cross references
• Running headers and footers
• Book titles
• Graphic cues and icons
• Layering – has two types of information on the same page to satisfy two types of users
  

A good software manual contains useful patterns to help the user identify information easily. Some structuring methods are cuing (including visual patterns – icons, rules, fonts, caps, etc.)

Indexes and tables of contents make up the two most important user tracking and navigational devices in any manual. And lists of figures and tables make up a main element in the usability of a document

Solutions for Online Documentation:

• Using nonscrolling regions so as the user reads down they don’t lose sight of the topic
• Expanded or stretch text allows you to put more into a topic by use of an expanded link
• Keyword searches helps user electronically find topics
• Indexes – most online help compilers will generate this automatically
• Links and jumps allows user to go from one topic to another easily
• Popups – quick way to toggle on and off added information or definition
• Context sensitivity – user goes directly from a problem with a screen or field directly to the help topic.
• Histories – users can retrace steps
• Bookmarks – annotations – newer online systems have elaborate ways to use bookmarks

Chapter 9 Campbell - No One Ever Told Me About That

Team 6 - Kathy Owens

I didn't know if the team assigned this chapter is still in existence, and since the chapter is so short, I thought I would put a quick summary up so we can add our comments:

Three choices for notifying users of new policies/procedures:

1. Announce it in person
2. Communicate it in writing
3. Send it by e-mail

Your choice is often determined by organizational norms.

Notifying in Writing:

• When you are writing for an external audience
• Audience is large or widely dispersed
• Complex or lengthy material
• Noncontroversial subject
• Personal contact unnecessary

Notifying in Person:

• When subject is sensitive or controversial
• Importance or urgency needs to be emphasized
• Unofficial expectations differ from the official policy or procedure
• Examples or elaboration are required to be fully understood

Notifying by e-mail:

• When you have online policies and procedures
• Organization is used to this type of communication, and users are comfortable with this

Make sure to accommodate users with special communication needs, and
Make sure your managers are notified first so you can get their support.

Barker Chapter 9: Editing and Fine Tuning (is essential to any form of writing)

In this chapter, Barker goes over the essentials to Technical Writing Editing and how that might be different than traditional Editing. However, it also has many similarities.

Barker talks about an in-house style guide for companies editing procedures. It is important to stay consistent throughout the company and not have different departments completing their tasks differently. Consistency is always key. The following are steps for editing software documentation, found on page 270.
English Project guidelines
2. understand types of editing
plan your editing tasks
Develop the appropriate editing forms.

The goals on page 270 also mention the above consistency, but breaks it down to how the user perceives the document and the purposes of the information in the documents. The goals also include applicability to multi or cross-cultural readers, correspondence of tasks and activities in a manual of help system and smooth interaction with editors and writers, along with the rest of the team.

Page 271 has a table regarding four types of editing which include the following:

Managerial
Substantive
CopyProofreading

Most people understand number 1 and 3, but Substantive editing is developmental editing, which means editing language and information (page 272).

Editing takes time

Table 9.2 on page 277 gives estimates on editing a particular document and Substantive editing requires about 6-8 pages an hour, Copy Editing 1-3 and proofreading 5-10 pages per hour. This table also includes activities that are involved with each task such as for Managerial Editing overseeing production, Substantive includes reading drafts and suggesting content, Copyediting includes correcting sentence clarity and structure and Proofreading includes verifying changes against copyedited pages and checking for layout/graphics consistency.

Barker says conducting editing sessions are very important so that there are no distractions while editing. Most people have other projects they are working on and can also easily get distracted by their co-workers. A good set of large earphones and a checklist are all suggestions Barker makes to ensure good editing.

This chapter also includes editing Graphics, which is a part of the Substantive editor’s job.

Writing Vs. Editing is discussed in this chapter because many people combine the two, but there are clearly differences such as

As a writer you work on generating ideas and content and an Editor concentrates on document standards and comparing information. (Page 280 has a more comprehensive listing).

Many Tech Writers have to think about their audience being the world, so Barker provides tips on how to write for them, too.

use active voice
use articles wherever possible
use simple verb tenses
use language consistently
avoid lengthy compound words
use relatively short sentences

Chapter 9 also includes tips on Editing for Translation, problems with editing online systems, and discusses how do you know what’s correct?

Translation Editing includes “checking for characteristics that allow for language to be easily rendered into another language, (Page 292).”

Problems with editing online systems include
Heavy emphasis on editing index, different production process for planning and scheduling, etc. (a more comprehensive list is on page 293).

Constructive Attitudes are important in writing and editing because you will be critiqued and you will have mistakes in your document, it is important to look at it like you need to perfect the document rather than you made all of these mistakes or you think it’s already perfect.

Team 2 Ender?Warren

Chapter 8 Barker Conducting Usability Tests
This chapter covers three basic types of tests
1. Tests for task performances (procedures)
2. Tests for skills and understanding (tutorials)
3. Tests for access to information (references)
A ten-step test plan is recommended to cover main tasks needed to perform when conducting usability test for large and small projects.
Test Forms
Figure 8.1 – a procedure test form
Ø You can adapt this form to fit your needs
Figure 8.2 – Guidelines for testing documentation
Ø This form can be used when testing procedures
1. Decide when to test
There are nine stages of documentation development
The best time to test is during three stages:
Ø Phase 3 design
Ø Phase 5 writing/drafting
Ø Phase 9 Field evaluation
2. Select the test points
Test points fall into two areas
Ø Problems with content
Ø Problems with document design
Select procedures for testing
Determine which tasks you will need to test based on where you think a mistake or error may occur. Keep in mind that you are not testing the user – you are testing the documentation.
Look at testing procedures that are complex, meaning they have ten or more steps, or a one-time installation, users can not learn from experience when they are doing these tasks only once.
Certain tasks create confusion and high failure errors; look for specific places that mistake will occur in your documentation – this can reduce efficiency and cost money. There are certain information related tasks that should be error free, they are
Ø Importing information from other programs
Ø Creating, naming, and formatting files
Ø Exporting information for other programs or other program formats
Ø Creating printouts and reports
Select Design Strategies for Testing
You should look at the following design elements:
ü Terminology
ü An index
ü Cuing patterns
ü Headings/layout
ü Navigation
ü Extraordinary document formats
Choose the Type of Test
Ø Table 8.2 indicates three types of tests in relation to the test points
Set Performance and Learning Objectives
Ø You want your test to measure the actual behavior.
Ø Performance does not always mean, getting the test done in the shortest amount of time
Ø Table 8.3 demonstrates types of performance objectives
Objectivity and Testing
You need to set up tests in a way that you are not prejudicing the outcome. No test can be 100% objective, but you cannot have your document passing with no problems what so ever, that is not reality. Bias can creep into your test without your intending it to do so.
Select Testers and Evaluators
§ The tester is the person administering the test
§ The evaluator is the person taking the usability test
Prepare the Test Materials
For testing in a Test Lab, more materials are needed and can be complex. But for purposes, we will be performing informal field evaluations. Check Tables 8.4, 8.5 and 8.6 for more information.
Pilot Test
It is probably a good idea to run a test pilot on your written material, you will check for the following:
Ø Are your instructions written so that your evaluators understand and will they be able to perform the instructions correctly?
Ø Check to be sure you are not using terms that the users can understand.
Ø Will the user be able to perform the test in the time you have allowed?
Set Up the Test Environment
You can set up the test at the user’s work environment or a controlled lab. To learn in the context of the user’s work it is best to perform the test in their work environment. A lab offers control, but is not always a choice that you have. Researchers recommend using a combination of test environments.
Record Information Accurately
Ø You need to use accurate methods to record what you see and hear during usability testing. Recorders can be used to record voice, also can used video recorders to record every movement of the evaluator.
Interpret the Data
Ø The data should tell you something about your users.
Incorporate the feedback
Ø Testing should be incorporated into the document design. You should re-test a few times and analyze the data.

Chapter 8 Campbell: Did I Forget Anything?

by Mary Dobbins

Creating a Perfect Document

There are 5 different types of review which should be done sequentially so most critical issues are addressed first:

Verification – Reviewing in the proper order saves time. Combining reviews for format, grammar, punctuation, accuracy, etc., is much more demanding and leaves room for error unless multiple reviewers are used.

Validation – Checking for accuracy involves making sure information is up to date, dimensions given are accurate, requirements are correct, etc. This can sometimes be combined with editing but usually works best as a separate task. User errors require altering wording to make document clearer; policy/procedure errors require change in content or sequence. Check for usability using ideally one or two other reviewers by: trying to gauge by their reactions if something is unclear, soliciting comments, or observing.

Editing – Be careful not to alter the meaning, edit for format, wording, consistency, flow, cohesion, layout, and visual appeal. Narrow the scope using a format edit, language edit, style edit, etc. Use your knowledge about the audience to guide your editing. Use consistent marking and a style sheet. Read aloud and use different colored pen marks. Review page layout, design elements, consistency and logic.

Proofreading – Credibility is the most important reason for proofreading. Decontextualizing, meaning taking letters, numbers and words out of context instead of grouping them together, is an effective proofreading tool. You can also read backwards, real aloud into a tape recorder or to a partner, or read diagonally. Look for typos, punctuation, spacing, spelling, agreement, page breaks, titles, misplaced words and phrases, alignment, names, numbers, typestyle, typesize, and margin errors. Don’t skip proofreading!

Approval – Communicating with approvers throughout the document process is important to avoid a possible rewrite. The approval process should be a formal procedure which includes time frames and encourages approvers and managers to solicit comments from their own areas. To facilitate quick approval, use a form that’s easy to complete. For lengthy documents, include a summary memo. Coordinate conflicting responses among approvers.

If possible, have others review your document rather than trying to do it yourself. Review the checklists at the end of the chapter for step-by-step guidance in completing the review types above.

What's the Secret to Creating Good Manuals and Handbooks

Team 6 - Kathy Owens

The secret is summed up by answering these two questions:

1. Can readers find what they're looking for fast and logically?
2. Will the book be easy to handle and hold up to daily wear and tear?

Users want easy access, physical convenience, and usability.

Seven (7) design elements - collectively referred to as front matter and back matter.

1. Table of contents - critical first impression to your readers and a negative one will discourage readers from reading it at all. Do the table of contents last, not first.
2. List of illustrations - Used for tables, photographs, graphics, etc. and appears right after the table of contents.
3. List of forms - Just like list of instructions and list of illustrations, but is just for forms. Most readers dislike forms. Having them in a list discourages the excuse, "I couldn't find it."
4. Introduction - Sets the stage for what's in the manual, such as purpose and scope. Helpful for all manuals, but keep it brief.
5. Glossary - List of special words, acronyms, abbreviations, jargon and terminology a reader needs to know. Kept at front or back of book. Keep it brief
6. Appendix - Info that supplements the text. Place it at end of section or at end of policy/procedure to which it applies. Traditionally, goes at end of book but readers hate to flip pages and may be overlooked altogether, so carefully consider placement.
7. Index - Most valuable "speed tool" of an alphabetical list of items in the manual. Many types of indexes. No matter what type, use terminology readers use. Indexes are back matter, but placement in manual can vary.

Six (6) Production Elements:

Main items to consider:

• How readers will use the manual
• Under what conditions will they use it
• How frequently they will use it

1. Size - standard dimensions are 8 1/2 x 11. Don't be bound by that but consider ramifications of larger or smaller manuals. Smaller manuals may get lost in the shelves with other books.
2. Paper - Heavy use of manuals might call for heavier pound paper, like 24-32. Location of use might call for laminated or plastic coated paper. Think of how and where they are used and plan accordingly.
3. Color - White is good, but don't be afraid to experiment, like colored paper for important pages, or for the table of contents or index. Don't forget that binder - if all the binders are black, pick red.
4. Binders - 3-ring are best if you are going to change the manual a lot. Spiral bound is good if you don't. Whatever you use, being able to open the manual flat is good. And, buy as good as budget allows. Cheap ones break. If you get them too big and it takes two hands to pull it from the shelf, it is not as likely to be used as one you can grab with one hand.
5. Cover - Popular are the binders with a clear, plastic envelope on the front. Don't forget an insert for the spine.
6. Dividers - One of the main 'speed tools' for accessing a manual. Make sure those are quality ones as well.

Distribution Issues - Develop a distribution list and get a signed receipt of acknowledgement from the person receiving the manual.

The psychology of the user:

• Big is daunting. Any document that needs to be carried with two hands is a candidate for the least-used.
• Most users reach for a handbook when they need an answer immediately (and easily).
• A good first impression (in the table of contents) will entice your users to read further.
• Most readers dislike forms and will find any excuse NOT to use them.
• People hate to flip pages. Placement is critical.
• A good manual has the good news first, bad news second, neutral news last.
• Users find illustrations convenient.
• Users like lists or tables of illustrations.
• Users like lists of forms; If you have a lot, you could even put them in a separate manual.
• Forms - they don't like using them, and don't like filling them out. Make them easy to find.
• Readers love a good index.

Chapter 7 Barker - Getting Useful Reviews

Team 7 - Jaeger/Lopez

To review documentation, you send it out to get the reactions of other people who are involved in the project.
Reviewing may take the most time compared to all other activities associated with document production.
Getting the most out of your review cycles - follow these 6 steps:

1.) Review the Document Objectives from the Documentation Plan
- Consider the documents objectives in the planing stage
- If applicable, make sure it meets company policy and reflects well on the company

2.) Determine the Type of Review Needed
- The kinds of reviews you design will depend, in part,m on the kinds of persons who have a stake in the documentation.
- Reviews offer challenges and problems, because not all of the persons whom you need to do the reviewing may be at your job, or may lack familiarity with your project.

3.) Establish a Review Schedule
- Make sure you give your reviewers enough time to fit the reading into their schedules.
- Careful reviews take approximately 1 hour per 15-20 pages.
- Sequential Circulation involves making only one copy of the document and then passes it to the next person to review it. Main advantage is minimal cost
- Simultaneous Circulation involves making a copy for all of the reviewers and receiving every ones review back. Main disadvantage is its expensive to create all the documents but you can tailor to diverse reviewers.

4.) Plan the Reviews
- A well-articulated review plan encourages you to think the process through by making it a goal-driven process.
- A plan provide3s background material to help reviewers respond more productively.

5.) Write a Cover Letter with Questions for the Reviewers
- To get relevant information out of your reviewers you should provide them with a cover sheet specifying what exactly you want them to pay attention to.
- Tell the reviewers exactly what you want them to do.

6.) Prepare Feedback Materials for Reviewers
- Reviewers need to know that you have read their comments and paid attention to them. Let each person know the effect of his or her work on your project.
- Use memos or thank-you letters for giving feedback to your reviewers

Reviewing Differs from Testing
Testing tends to concentrate on users and issues of accuracy and statistics. Reviews develop information about conformance of a product to management schedule and company policy. Also, reviews don't produce quantitative data about a document or statistics.

Reviewing Differs from Editing
Editors bring their training in editing. Reviewers such as managers, subject-matter experts, and programmers bring their professional opinions.

The Purpose of Reviews
Communication function - help communicate with people associated with your project
Management function - help you manage your project
Quality assurance function - help you maintain the quality of your product.

Reviewing Throughout the Documentation Process
Planning and Design Stage - your documentation plan should undergo thorough testing and review by managers, clients, and users
User Analysis Stage - an audience analysis should be presented to your managers, clients and users as a way of checking their validity and accuracy.
Development and Writing Stage - early in the development process you should validate the accuracy of your task list.
Draft Stage - you may want to schedule and implement draft reviews of parts of the document that have reached completion.

Reviewers as Partners
Tell them the benefits of participation - Make your reviewers understand that not only you benefit from them reading your document, but they also benefit.
Don't abuse the privilege - Don't overuse a good reviewer.
Show them revisions - Share your revisions. If you managed to get good feedback from reviewers, let them know how you used it.
Hold review meetings or walkthroughs - Have reviewers meet each other.
Keep contact over time - Keep a file of information about the work they have done which will help you avoid overusing them.
Return the favor - Don't compensate them. It's good business practice these courtesies in a meaningful way.
Thank them in print - When you have the opportunity, list the name of those who reviewed for you.

Negotiate Changes Diplomatically
Be firm only when necessary - The more you respect another culture's tendency to leave things undecided, the better chance you have of discovering a solution in the future.
refer to the Relationships Rather Than to the Person - Reinforce relationships when dealing with cultural conflict.
Acknowledge Cultural Differences and Give them Value - Engineers come from a "high context" culture where writers come from a "low context" culture. Compromise between the two.

Do a User Walkthrough
This is where you present the document form end to end and focus on the key issues of usability.
How to Set Up a User Walkthrough
1.) Decide on the issues you want to examine.
2.) Choose the attendees.
3.) Prepare a meeting agenda.
4.) Make copies and provide files for all attendees.
5.) Run through the walkthrough. Begin by announcing the agenda.
6.) Do a follow-up review. Send copies with the suggested changes to users after the meeting.

User walkthroughs offers a number of advantages for writers and users. Users can have a say in the development of the documentation and allows you to gain valuable insight into the usability of your document.

Planning and Writing Your Documents

Chapter 6 Barker
Katy Mears and Erik Sorensen

There are nine phases in the documentation process. They are:
1. Start the project
2. Perform the user analysis
3. Design the documents
4. Plan the documentation project
5. Write the Alpha Draft
6. Conduct Reviews and Tests
7. Revise and Edit
8. Write a Final Draft
9. Conduct a Field Evaluation

This chapter also summarizes development of online help systems. Each guideline includes an examples and project plans.

1. Start the project
-Get to know to software you are writing about
-Remember that a good manual is based on the user, not the software
-Writers will most likely work in teams. There are two kinds of teams: development teams and writing teams. Development teams have members who deal with the programming, planning, and marketing of the product. Writing teams members write, edit, and test documents (175).

The Development Team (176):
-Develops entire product—both software and documentation
-Persons on team include product developer (designs program, considered expert on subject), project manager (organizes project and keeps members on track), market/systems analyst (studies users and activities that the documentation will describe), technical specialist/programmer (writes and tests the program), and documentation specialist (handles writing of manuals and help programs).

The Writing Team (176):
-Develops documents for program
-Not always “clear distinctions” between roles
-Persons on team include manager (in charge of overall project, keeping members on task, and maintaining documentation plan), lead writer (does user analysis and writes drafts of documents and topics), writer (creates content), editor (edits documents and sets up consistency standards), graphics designer (handles artwork and screen captures), and tester (maintains documentation quality by testing the documents).

Preliminary research is a part of starting the project. There may be documents developed by the members of the developing team about the software. These documents include project plans (identify goals and justification for the software and may also include what problem the software intends to solve), program specifications (instructions on structure of program and what operations need documentation), market analysis (sales research on software buyer—not to be confused with user, who needs to be able to understand the documentation), information plan (the documents needed by users), and management plan (resources, people, and schedule for completing the project). The information plan is most valuable to the writing team because it is focused on the user’s needs (178).

Online Help Development Process (179-184):
An online help system is in WinHelp or HTML format. It is arranged around user’s workplace activities and contains different types of documents about the program. This format can contain more clever and helpful ways of presenting information because of technological advances. The stages of development are similar to the nine stages in documentation. However, user analysis focuses primarily on workplace activities and the user’s software skills. The time management schedule will vary to prepare for “inevitable delays” that can occur in developing the program. Testing the help system is also more complex because of hyperlink testing and troubleshooting. Writers also need to test in different environments because the program will be used in a variety of “computer platforms (Windows, Macintosh, Linux, etc).”

The first decision the writer needs to make when starting a help project is to determine what “authoring environment” (software program that you will use to write help documents). Different programs have different features. A usable program should have single-source capabilities, authoring features, and management features.

2. Perform User Analysis (184)
-Research what makes the software effective by interviewing and observing the users
-Develop a table of contents based on these tasks
-Default Manual: a manual that “records the functions of menu items, commands, and dialog boxes, but doesn’t structure the information according to user tasks (185)”

3. Design the Documents (187)
-Apply the three types of documents (tutorials, procedures, and reference) to the user
-Outline documents and determine layout

4. Plan the Documentation Project (189)
-Write a project plan for deadlines and to clarify each member’s responsibilities
-Design plan: plan for document design
-Documentation plan: specify manuals and outline help if needed. This will be the main document in organization
-Project plan: plans for further research and other design work. Project plans include information about meetings, deadlines, project report deadlines, test completion notes, review deadlines, and edits. It should also include estimates for document length and the amount of time it will take to complete it. It should also list the resources to use to complete the project such as human and material resources. Human resources are the efforts of the sponsors, users, testers, reviewers, and editors and their time should be planned for accordingly. Material resources include the computers and equipment on the project. Writers should be familiar with the technology they will be using.
Assign People to Tasks
-Determine roles of team members
Editor-writer-tester-graphics designer-review coordinator
-Keep in mind the talents of your staff, assign people to their strengths
-Writing skills
-Editing skills
-Software tool skills
-Subject matter expertise
-Familiarity with environment

Calculate Time/Page and Screen Estimates
Sometimes it’s easier to use a formula to estimate the time and length your documentation will be. There are some things to keep in mind:
· Type of documentation – Tutorial, procedures or reference document you may need to add information. Tutorials take more space because of listing explanations conversely documentation requires only the bones and takes less space
· Availability of information – If information about the documentation is not readily available you may need to add time
· Experience of writers- Writers with more experience can do more work in less time. The more experienced the writer, the faster the product can be completed
· Reliability of the program-If your program is being tested while you’re working on it then it may take longer to complete because you will be revising it as you go

Write the Help Project Plan
Some documentation requires both online help and print help topics. In this case your documentation plan will reflect both. In the Sevensteps authoring environment the program is designed to work with four people: Project Leader, Author, Domain Expert and Developer. The estimator will use formulas to calculate how much time each person working on the project needs in order to complete a given number of tasks.

Reviewing the Documentation Plan
The documentation plan will go through a thorough review by managers, clients and users. The documentation plan gives you the opportunity to hold a user walkthrough and a technical walkthrough.

#5 Write the Alpha Draft
The alpha draft represents your first complete document including all the front matter, text, graphics, appendixes, indexes and associated documentation set materials. Follow style guidelines and it is a good idea to create an alpha checklist. It may be a good idea to because this will show other writers what has been done,



Draft the Help Topics
Writing help topics requires that you not only supply content for each topic, but supply information about the topic that the system uses to relate it to other topics. Writing of topics involves creating content, but also creating important links and interconnected relationships among topics and recording them using the help authoring system. Once the topics are written a special program call a help compiler is needed to read the topic. Often you will encounter errors in creating help topics such as unrelated or cross related topics.

#6 Conduct Reviews and Tests
Because the alpha draft contains all the elements of your product, you can send it out for review by clients, executives, and managers, as well as users. You can also design usability tests using the original documentation objectives, to test for elements such as accuracy, task orientation and so on.

Conducting Reviews and Tests of Online Help
Testing occurs after the compiler has successfully created a version of the help system that you can circulate among users and clients Testing will occur often and therefore it is important to separate and schedule testing of the technical elements and content accuracy.

#7 Revise and Edit
You can often revise and edit your own work then submit any changes to the editor or just simply continue editing your own work. This will allow checking for accuracy on many levels.

#8 Write a Final Draft
Writing a good final draft should be accomplished a lot easier if you have done a good job in the previous stages

#9 Conduct a Field Evaluation
This is the last stage of evaluation. From this stage you can analyze and gauge how well your document and help system met the needs of the user. You can provide the user with feedback links in HTML format or simply give them email links in order to provide you with the necessary feedback for your product.

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

Larson/Tradup

First impressions count!

Set the Stage
Investigate if internal communication is effective and be prepared to explain why your new document is a better plan.

Hooking your audience
Remember rule: appearances count

• 70% of what you know is based on appearance
• your reader assess simplicity, form, clarity, shape, color, highlights, density, sharpness, and contrast at a single glance
• they want to know if your document is worth their time
• they don't want chaotic, crowded, noisy documents

Use the hidden documents design to:

1. get readers in the door
2. encourage them to stay and read

Create Visual Appeal

Hidden power of document design is what it does for the appearance of your document. Remember the Madison Avenue lesson: "If it looks organized, uncrowded, and easy, it must really be."

Avoid Visual Clutter

Visual clutter is the result of a document that looks overwhelming; "that stuff in the garage." Two things are required for an easy-to-read and look at document:

1. simplicity
2. clarity

Designing for Visual Appeal

How can the clutter be controlled? By using basic design elements to make the document look easy, fast, and clear, i.e. visual appeal:

20 basic design elements

sentence length, paragraph length, line spacing, typestyle, typeface, emphasis, paragraph spacing, justification, indentation, margins, headings, graphics, visual weight, contrast, color, symbols, columns, lists, forms, white space

Why do design elements work?

1. the human brain

-can deal with as many as seven different items at one time

-can clearly distinguish among only three of the seven items at one time

Solution: use the Rule of Three

2. eye movement

-takes in about forty characters at once

Solution: consider using columns, break information into chunks

-takes in three or more words/second

Solution: use headings, sections, concise wording to make message obvious

-reads two or more words at one time

Solution: reinforce unimportant words that carry critical meaning; avoid excessive adjectives, descriptors, fancy phrases, complicated clauses

-moves top to bottom, left to right in a Z pattern

Chunking as a visual technique

• present information in small, simple chunks that are well organized
• white space: the more white space, the faster the document is read

Consistency is all

Help readers develop a rhythm for comfortable reading

Chapter 5 Barker Analyzing Your Users

Hope it's ok to blog for this chapter without an initial posting...
The audience/user needs are so important and this chapter provides a good list of tips for analysis such as worker's motivations, level of computer use, knowledge of program's subject matter, learning preferences, and usage pattern to list some of them. I especially agreed with the idea of including those who have a personal stake in the outcome with the planning, implementing and revising of any new program. This approach changes the procedure writer from an overseer position to a collaborative position. I've found this approach definitely makes the users feel their ideas and suggestions are important and this provides an atmosphere of teamwork. I've been a usability testor for various new web page applications at work and when the administrators of a new program encourage my feedback, I feel open to express more than I normally would about the process. This also increased my motive to learn a new program. Barker wrote about the role that attitude plays in introducing a new program so when I write my usability testing document, I will remember to include the benefits for the users prior to testing. I also need to take into account users' prior knowledge, learning methods and experience in order to hit my target audience.

Campbell: Chapter 5 Is There a Certain Format I Should Use?

Chapter 5 Is There a Certain Format I Should Use?
Team 2 Ender/Warren

Format and Audience
The format is determined by your audience and what information you are presenting. Some formats work better with certain audiences. For example, flowcharts work great for engineers and other types that have a technical background. At the same time, the visual elements of a flowchart may be overwhelming to a person in a technical field. People react better to formats they are familiar with. Many times, new formats are confusing and can take adjustment.

Format and Material
The content that you are sharing in the document narrows the format options that you should use, for example: Safety documents need absolute clarity, easy comprehension and immediacy. In this type of situation, an outline format or flowchart that contains arrows would offer more clarity and ease access for the user.
For Procedures that are very detailed and precise – flowcharts work great. As the writer, you need to analyze the content and decide which type of format works best.
Narrative formats usually work better for policy statements and general information.

Format and Management
You need management on board with your choice of format – explain why this will work best for your document. Always keep the reader in mind.

Deciding on Page Layout
Whatever format you choose, certain elements must be consistent in the page layout. The user must be able to find the title, document number, effective date, and revision, all found in the header/footer depending on your company’s document style.
Purpose, scope, background, or required equipment, are part of the page layout as well – this information is usually found at the top of the document preceding the actual procedure itself. These sections are usually written in narrative paragraph format.
Most companies standardize other information on each of their documents, this facilitates a consistent document and the user will find all information with ease. The main objective is to keep the document simple so reader can find the information they need.

Choosing Among Format Options
Once the page layout has been decided, then you can choose the format for the main text. The important thing is to be consistent; clarity helps the user so that they are not confused.

There are several Primary formats to choose from:
• Narrative – standard sentence paragraph
• Outline – separated into sections and subsections
• Playscript – formatted by actions and responsibilities
• Flowchart – a diagram or process
These formats can be used alone or in conjunction with other formats and they are the basis of the document.

There are several Secondary formats to choose from:
• Questions and Answers – narrative or table format
• Troubleshooting – help sections/reference sections
• Matrix table – variable placed in the header/one variable placed in the stub (to the left)
• Lists – short lines, the eye loves these shorter line lengths

Combining Formats
Minimize the confusion in documents and only combine formats that are necessary in a policy and procedure. If used correctly, certain combinations of format can be very effective.

Experiments and Hybrids
These formats should not be considered sacrosanct, any and all of these formats can be changed to fit your needs. Experiment with them to see which ones work best for your audience’s needs.

Barker Chapter 4 – Writing to Support-Reference

by Mary Dobbins

Chapter 4 deals with the three main levels of support: teaching, guidance, and reference. The level of support used is determined by user behaviors, questions, and needs. The various forms of reference are described as follows:

- Appendices – highly detailed, technical documentation such as error messages explanations, filenames and extensions of files associated with the program, troubleshooting tips, compatibility information, fast-key options, printer driver charts, and FAQ

- Readme files – installation details, changes not included in the manual or online help, new features in program, revision histories, errors in manuals and online help, file descriptions, contents of directories, installation tips, and compatibility requirements


- Job aids – shorter document that may include keystrokes, definitions, brief processes, command summaries and other useful information

- Flipcards – contains brief program information on a card that fits on a monitor. Typically, flipcards are easy to read, contain a lot of valuable information, use colored headings, are unique and interesting, and offer easy access to information


When developing references, you must decide what to include. The text suggests:

- Commands – explanations of set and format commands, special procedures, and toolbars

- Interface elements – explanations of menus, keys, screen labels, and rulers


- Definitions of terms – glossary

References should be written in a consistent pattern and arranged in a manner that makes sense to the user such as alphabetically or preferably, menu by menu. The text indicates it is necessary to show the user how to use the references and also to understand how the typical user will use the references.

Chapter 4 (Campbell) Group 7 Jaeger/Lopez

What’s the Best Way to Word This?

Technical vs. Narrative Writing

Technical Writing – purpose is to get the message across quickly and clearly
Narrative Writing – purpose is to impress the reader

*Clarity and Speed are the only two criteria’s needed to write technically. If users clearly understand what’s expected of them and can understand it fast, you have a successful document. Simple is good. Get rid of pompous, stuffy language. Eliminate unnecessary verbiage.

The Policy and Procedure Writers Oath – I do solemnly swear to avoid excess verbiage, fancy phrasing, and long words and sentences. I will resist the temptation to display my grammatical mastery and linguistic skill. I will devote myself to the pursuit of short, clear messages. I will dazzle with speed and clarity. ( Ha ha, I love it!)

Being a Word Miser

People who use only the number of words necessary and want to get rid of every single word that doesn’t mean something. To become a word miser follow these simple steps:

Think in Ones

One word is better than two. Two sentences are better than three. They look for any additional words that they can take out but still have the same meaning. Example:

Use the designated hammer.

Do you really need to specify designated?

Dump Pompous, Stuffy Language

Use active voice, start with an action verb, and eliminate all unnecessary adjectives. Example:

All rental car reservations must be made through our affiliated travel agency.

Better -> Reserve rental cars through our travel agency.

Speak to the reader

Type like you are directly talking to the reader. Simple, common language is exactly what you’re looking for in most policies and procedures. Talk to the readers out loud, then write down what you would say.

Follow the Word Misers Rules to Live By Think active voice, present tense. Subject, verb, object. Form your sentences this way, it is called active voice. Active voice cuts out a number of words and clarifies who does what. Add present tense to give a sense of immediacy.

Be an Accurate Word Miser

Be sure not to take out critical information. Don’t cut words mindlessly. Always ask whether a word or phrase adds any meaning. And if you can’t be both brief and clear, always choose clarity.

Being a Word Master

Use words with precision and respect. Instead of using very long sentences to describe procedures, break instructions into steps; numbering or lettering them.

Understand that every word has a meaning. Describe statements like: Turn the handle to the left. More like: Turn the handle slowly to the left until it stops. Do not force the handle. Say precisely what you mean.

Say What You Mean and What You Say

Use Specific Language

Avoid vague words that invite varying interpretations. Describe what “cool” is not by a word, but rather “45 degrees Fahrenheit”.

Developing a Rhythm

Rhythm is what keeps the reader reading. Two sources of rhythm: consistency and parallelism

Consistency

Varying your words often confuses the readers. Use the same word to describe the same action or object throughout. Creativity doesn’t count.

Parallelism

Use the same grammatical format for like items. Use the same future tense or the same passive or active voice to make instructions parallel in form.

Consider the Reader

Don’t Assume Anything

Don’t assume the reader will understand. Statements that require prior knowledge assumes the readers know what to do. Do not fall in this trap.

Look at the Reader’s Experience

Pay attention to your audience. Diversity of user experience poses a challenge. Visualize the least experienced user and write for that person.

Use Jargon Carefully

Don’t presume that terminologies are common just because you know them. Once again, analyze the audience carefully.

Distinguish Between Users and Readers

Users take action, readers don’t. Write for the user.

Calculate Reading Level

Well over 50% of today’s workforce reads below a ninth-year level. You must consider this. Write for the 6^th – 8^th grade reading levels, the same as most newspapers write to.

Word Documents Carefully

Using Special Techniques for ProceduresAvoid words that provoke unpleasant reactions. It will increase receptivity and reduce resistance.

(These are pretty simple so I am not going to describe them too heavily.)

Start With an Action Verb

Use One Action per Step – makes instructions easier and faster.

Assign the Action – If multiple users are involved, it’s critical to clarify the responsibility.

Park a Sentence – The most powerful position in any sentence is the beginning and end. Place keys words first and last.

Choose the Right Format – Play script is the best and clearest format for most procedures involving more than one person. Outlining and lists work well also.