Campbell Chapter 9

No One Ever Told Me About That

You have three choices for notifying users about a policy or procedure.

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

Which one you choose will be based on part preference and part circumstance.

Factors that determine how you notify your users depend on:

• Amount of material
• Nature of the material
• Complexity of the subject
• Organization's standards
• Communication method
• Size of user group
• Urgency
• Location of users

Notifying in writing

Pros to notifying in writing are that it communicates the policy or procedure in a uniform way to all users. It can be distributed in mass and reaches users at all locations, on all shifts. It serves as legal documentation. And it formalizes and reinforces the message.

Cons to notifying in writing are that remote locations and later shifts may get their copies late and feel slighted. It may sound rigid or bureaucratic. It eliminates personal contact and the ability to ask questions directly of the issuer.

Tips for notifying in writing:

• You're writing for an external audience such as an accrediting agency or customer
• The audience is large or widely dispersed
• The material is complex or lengthy
• The subject is noncontroversial
• Personal contact is unnecessary

Notifying in person

Doing this can take many forms: group meetings, individual meetings, phone conferences, or videoconferences.
The main advantage of notifying in person is that is gives direct contact with the issuer, which tends in increase cooperation and reduce resistance.
The main disadvantage of notifying in person is that meetings can be both hard to coordinate and unpleasant to conduct.

Tips for notifying in person:

• The subject is simple or the user group small
• You need to convey a sense of urgency or importance
• The policy is ambiguous and needs explanation
• Unofficial expectations differ from official policies
• The subject is controversial or sensitive

Notifying by e-mail

E-mail is a hybrid approach to notifying allowing the user to ask questions to a written announcement. E-mail is best used when you have on-line policies and procedures or most of the organization's communication flows through an e-mail system and users are comfortable with it.

What to put in your notices

Written notices

Identify the policy and procedure
Give a summary of it
Include logistical information (title, number, effective date, implementation time frame, who's covered, whom to contact with questions or problems)
Include a brief summary of the substance (reasons for it, basic provisions, user responsibilities, and the impact it will have on users)

Verbal notices

Will the information session be introductory (brief and very general), informational (lengthier, containing more substantial information), or a training session (lasting as long as necessary covering all operational details)

Notify managers first before issuing a general notice to the company. Getting managers on board will keep their staff in line behind them.

Campbell Chapter 8 - Did I Forget Anything?

I want to apologize for not posting this earlier. I guess I wasn’t paying attention yesterday, and I clicked ‘Save’ instead of ‘Publish.’ I think it’s quite fitting for the Did I Forget Anything? chapter. Oops.

Campbell begins this discussion by stating that the writer of a document is ultimately responsible for mistakes and errors. Therefore, a writer’s goal is to make both content and form as nearly perfect as possible.

To create a perfect document, it must go through a review process, which fine-tunes the document and double-checks for accuracy and spelling. Since this can’t be done at once, there are five different types of review, each dealing with a different aspect. These reviews include: verification, validation, editing, proofreading and approval. Campbell notes that these reviews can be combined, but it’s a much more demanding task and requires greater skill on the reviewer’s part. She suggests using multiple reviewers to speed the process, but the real key is to build adequate review time into the schedule up front.

Campbell then goes on to discuss verification. She notes that verification and validation are often skipped, but they shouldn’t be because they provide the foundation of the finished product and are the main concerns of both the reader and the organization. When you verify, you’re checking for accuracy. There are a number of different verification methods, which include: comparing the final draft to the original, checking it against source documents, confirming numerical and statistical data or assigning a content expert to do the review. Campbell writes that verification is especially important in procedures, where near perfection may note be good enough.

Next, Campbell discusses validation, which is checking for usability. She writes that you should read the policy completely through to see if it makes sense or if anything is missing. The best way to validate a policy is to have several people read through it and watch their reactions. Make notes of their reactions and ask them for honest feedback. Campbell also notes that validating procedures takes longer because you’re actually testing the steps and the sequence. There are numerous techniques for validating procedures, which include: walk-throughs, observation, focus groups, and surveys. Each of these methods require you to go through the basic steps of preparation, testing, debriefing, and documentation.

The next review process Campbell discusses is editing. She writes that it presents the unique challenge of improving the policy or procedure without changing the meaning. The main purpose of the review is to check for items such as format, wording, consistency, flow, cohesion, layout, and visual appeal. The number of edits you to through depends largely on the document and the project. Campbell notes that you should be careful not to confuse the function of editing with the functions of validation and verification. To edit, you must know what you want from your document. In the case of policies and procedures, it’s readability and usability. The mechanics of editing are largely a matter or organization and consistency. Campbell continues by writing that editing should be done with an eye to the important matters of mechanical correctness, because trivial ones will be caught in proofreading. When you edit, you should review the page layout, consider the design elements, and scrutinize everything for consistency and logic.

Campbell continues with the next review, which is proofreading. She writes that it is as important as the other reviews, but for a different reason, which is your audience assumes that if you let little things slip through, you’ve probably let some big things slip through too. She also writes that proofreading has a bad reputation because it is seen as boring, but it is actually a demanding, time-consuming step that requires discipline, concentration, and patience. Campbell notes that the secret to effective proofreading is decontextualizing, which means that you must reverse the learned habit of reading for meaning and concepts. There are a number of ways to proofread, which include reading backwards, reading aloud, reading into a tape recorder, reading to a partner or reading diagonally. When proofreading, you should look for every single imperfection, typographical errors, punctuation, spacing, spelling, agreement, page breaks, titles, misplaced words and phrases, alignment, names, numbers, typestyle, typesize and margins. Campbell also notes that you should be especially careful when proofing graphics, and to be aware of personal blind spots. When proofing your own work, Campbell emphasizes decontextualizing. If you are under time constraints, Campbell suggests having different people proof for different aspects simultaneously or using free-proofing.

The last review process Campbell discusses is approval. You should talk with your approvers throughout the process and not wait until the end. If you consult them periodically throughout the process, your writing won’t come as a shock to them. Your approval process should never be haphazard, casual or done at the last minute. Instead, your procedure should outline the approval cycle and time frames. It should also encourage approvers to solicit input and comments from within their own areas. Often, slow response from approvers causes a time problem. Campbell suggests using a well-designed form that’s fast and easy to fill out to help conquer these delays. According to Campbell, you shouldn’t be disturbed if your approvers don’t agree. This helps you identify differences of opinions before the policies and procedures are in force. Your job with differences of opinions is to coordinate and communicate. Campbell also writes that you should try to include unofficial approvers because they are influential people who give an unofficial thumbs-up or thumbs-down on the final product since they will use the product every day.

Campbell concludes this chapter by discussing who should perform these reviews. She emphasizes the importance of having other reviewers look at your work because they bring a fresh eye and a fresh perspective. They also bring their own marks and styles, so it is important to coordinate and communicate effectively with these reviewers. Campbell notes that at times another reviewer may not be available. In these cases, you’ll have to exercise twice your normal discipline since you’ll be the sole developer, researcher, writer and reviewer all at once.

Barker - Chapter 8 - Conducting Usability Tests

Writing Software Documentation: A Task-Oriented Approach

Thomas T. Barker

Chapter 8 – Conducting Usability Tests

Barker defines the process of testing documents as “procedures for gaining empirical data about [their] usability.” This is accomplished using three basic types of tests: procedure tests for task performance, tutorial tests for skill and understanding, and reference tests for access to information. The chapter presents a 10-step test plan for conducting these tests.

Guidelines

Good testing requires careful planning. Barker suggests the following 10 steps be followed.

Step 1 – Decide When to Test

Testing often occurs after a draft of the documents has been produced, however it can take place at various stages in the project depending on your testing goals. A Predictive Test can be conducted during the design stage, a Remedial Test during writing or development, and an Evaluative Test after the document has been completed and delivered.

You must also determine what parts of your documentation you want to test. Determining this can be assisted by relying on the objectives that you set for your documentation, and the user analysis that you previously performed.

Step 2 – Select the Test Points

Test points are issues or features that can interfere with the efficient and effective application of a program to a user’s work activities. These can include problems with content and problems with document design.

Try to identify points where a mistake on either of these levels could lead to user failure. Any procedure where the cost of user confusion or failure is high in terms of time or money would be a good candidate for testing. In addition to testing these procedures, you should also test the document design strategies employed to ensure that they are effective.

Step 3 – Choose the Type of Test

There are three types of tests. Performance Tests test whether users can successfully complete a given procedure. Understandability Tests test whether users can provide evidence of what they have learned. Read-and-Locate Tests test how effectively users can locate a given topic of information in a documentation set.

Step 4 – Set Performance and Learning Objectives

Performance objectives state how long a procedure should take or the frequency of correctness one can expect from users. They can be time-related, or error-related. The goal here is to collect numbers that can be analyzed and compared.

In order to produce objective test results, it is important to avoid letting the outcome of the test be skewed by bias. Prejudices can creep in as a result of various work pressures, a proforma testing atmosphere, or becoming too enamored with the product of your labors.

Step 5 – Select Testers and Evaluators

The tester is defined as the person who administers the test. The evaluator is the person actually taking the usability test. If you do not have actual users available, you will have to compromise by selecting individuals to stand in for users.

Step 6 – Prepare the Test Materials

The written and other materials provided to testers and evaluators can be very extensive. Barker lists multiple forms of test materials, both written and hardware/software based. He also discusses the importance of pilot testing, which basically amounts to “testing the test”, to ensure that the instructions, terminology, and time expectations are appropriate.

Step 7 – Set Up the Test Environment

The test environment can range from the user’s actual workplace to a controlled laboratory. A field test produces valuable real-world insight, while a testing lab offers greater control over the process. A combination of both environments is often the most effective approach.

Step 8 – Record Information Accurately

It is important to accurately record what you see and hear throughout the test. This can be accomplished using video and audio recording technology, in conjunction with copious note taking. Making use of additional observers can help fill in any details that you miss.

Step 9 – Interpret the Data

There are a number of phenomenon that can cloud the data obtained through testing. Once these variables have been accounted for, you can make changes to your document based on what the numbers reveal. These can inspire all sorts of design decisions that require skill and commonsense decisions on the part of the author.

Step 10 – Incorporate the Feedback

The final step is an obvious one. The information gleaned from the testing process should serve to enhance the document in a positive way.

Discussion

In this section Barker offers a variety of thoughts on the usability testing of technical documentation. These include topics such as:

• The three components of usability testing: tester, evaluator, and subject matter.
  
• The importance of user testing as part of user-driven design
  
• Comparing field tests and laboratory tests
  
• The cost of testing and making it a corporate priority
  
• Various field testing methods
  
• The trade offs between testing earlier and testing later
  
• Distinguishing between problems with the documentation and problems with the product

Barker concludes the chapter with a glossary of terms and a checklist for use when planning and executing usability tests.