Writing Effective Messages - Michelle Carey

© 2014 IBM Corporation

Writing Effective Messages and

Measuring Success

Michelle Carey

IBM Information Architect and Technical Editor


Agenda

Error prevention

Guidelines for writing effective messages

Measuring success

Quizzes (who doesn’t love a quiz?!)– Take these are your leisure; have fun with your teams!

2


CREATING AN ERROR-FREE UI (OK, ALMOST…)

Before you start writing messages, prevent errors in the first place

3


Error prevention

Prevent users from making mistakes by designing useful, intuitive, and relevant software and hardware.

Prefill fields when possible and use predetermined menu selections instead of text entry.

Detect values such as folder names and installed software.

Add effective embedded assistance so that users understand interactions, values, and choices—say why, not so much how.

Be consistent with terms, functions, and behavior.

Test, test, test, and test some more.

4


WRITING EFFECTIVE MESSAGES

So you’ve made your interface intuitive, useful, and relevant, but errors can still happen

5


Follow these guidelines to write effective messages

Focus on the user problem, not the error.

Don’t use overly technical jargon. Know your audience.

Convey the right tone.

Don’t blame the user.

Don’t use doomsday phrases.

Never promise future fixes.

Be complete:– Provide useful explanations and user responses.

Give translators and nonnative speakers a break.

6


Focus on the problem, not the error

7

Close

Error

CAT12233E

An error occurred while starting the service. Contact your system administrator.

An error occurred….So now what?


Focus on the real problem, not the error

8

Better:

Close

Error

CAT12233E

The service cannot be started.

Explanation: The application server might not be running, or your session expired.

User response: Ensure that the application server is running. If your session expired, log in again and start the service.


Limit or target the jargon

9

Close

Error

CAT12234E

The {0} template was not found in the target object store.

Explanation: The API call accepts the symbolic name, but the value that was sent does not resolve to a valid property template in the target object store.

Administrator response: Ensure that the symbolic name of the property template that is sent in the URI exists in the target object store.

Who is the target audience: administrators or office workers?


Limit or target the jargon

10

Close

Error

CAT12234E

The {0} template does not exist.

Explanation: The template might not have been created for your repository.

User response: Ask your administrator to create the template.

Administrator response: Ensure that the template symbolic name that is sent in the URI exists in the target object store.

Better message for office workers:


Convey the right tone

11

I read this once, and I’m amused.

I read it twice (after another outage), and I’m not amused.


Convey the right tone

12

Patronizing

Informal without being condescending


Cutesy, hipness, and chatty have their limits

The wrong tone at the wrong time isn’t good.– Imagine a cutesy error message that tells you that your checking

account was just wiped out.

Slang and humor are problematic.– Many people won’t get it

– Goes out of date fast

– Nearly impossible to translate

13


Don’t blame the user

14

So, yes, users make mistakes, but if you want to keep their business, don’t point your finger.

Write the message so that the user is not directly blamed for the error. If necessary, use the passive voice, for example:

The email address cannot be used. Ensure that the spelling is correct or that routing information such as @STUFUS is added to the address.


Don’t blame the user

15

Instead of “You are not allowed to use any of the following characters…,” how about something a bit friendlier:

Close

Error

CAT12235E

A user ID cannot contain any of the following characters: / # : & %


Don’t blame the user…or else!

16


Don’t use doomsday phrases

17

Focus on the problem and the fix, not how awful the problem is.

Close

Error

CAT12236E

A fatal error occurred during a Windows Server Backup snap-in operation. Error Details: Catastrophic failure.

Close Windows Server Backup and then restart it.


Don’t use doomsday phrases

18

How about something less earth-shattering:

Close

Error

CAT12236E

The backup cannot be completed.

Close Windows Server Backup and then restart it. If the problem persists, contact Microsoft Support.


Never promise a fix or feature

19

You put your company at legal risk for customer complaints or even lawsuits if you don’t deliver exactly what the customer expected.

Close

Error

CAT12237E

TIFF files are not supported by this viewer. This file type might be supported in future product releases.


Never promise a fix or feature

20

No promises here:

Close

Error

CAT12237E

TIFF files are not supported by this viewer. Use a different file type.


Be complete: provide useful explanations

21

Explain what’s wrong so that users can avoid the problem.

Does this explanation help?

Close

Error

CAT12238E

The file that you specified cannot be found in the {0} directory.

Explanation: No file can be found in the directory.

User response: Do this task….


Provide useful explanations

22

Close

Error

CAT12238E

The file that you specified cannot be found in the {0} directory.

Explanation: The file might not exist or might not have read or write permissions.

User response: Do this task….

This message describes the source of the problem:


Be complete: provide helpful solutions

23

These messages don’t help me solve problems.


Provide helpful solutions

Provide complete instructions, use examples, or add links to more complete info.

Even if you don’t know why a problem happened, at least give users some ideas about what to check, start, run, enable, and so on.

In some cases, explain the consequences of not taking actions, especially for warning messages.

If the user isn’t supposed to do anything, say so.– If the user does not need to take action, say “No action is required.”

24


Provide helpful solutions

25

Close

Error

CAT12243E

The document cannot be parsed.

Explanation: The index server might not be running.

User response: Start the index server by running the following command: esadmin start -user_name -password

Instead of saying simply “Start enterprise search from the command line,” provide the complete command:


Give translators a break

26

Here’s how to be mean to translators:

Instead, use something like this:


MEASURING SUCCESSHow do you know that a message is effective?

27


Several ways to measure success

Fewer problem reports

Message scoring

28


Reductions in problem reports

Your organization or company should have a way to classify and track problem reports.

Work with your Support teams to find the reports that mention error messages as the reason for the support call.

Ask the Support team to compile a list of problematic messages for your products.

Improve any error messages that are associated with a problem report.

29


Message scoring: the criteria

Message scoring rates the usability and effectiveness of a message by using the following five base criteria:– Accuracy

– Clarity

– No user blame

– No unnecessary imperatives to call Support

– Completeness

You could add other criteria.

30


Message scoring: the score

Messages either pass or fail.

They pass only if they meet all five criteria.

31


Message scoring: the process

You can implement scoring however you want, but I recommend this process:

1.If you can’t educate everyone on how to write effective messages, the message editor scores each message and records the score and reasons for failure.

2.Message author fixes the failed messages.

3.Editor rescores the fixed messages to ensure they meet the five criteria.

32


Le fin

Questions?

33


Backup


Use concise but complete, grammatically correct sentences

Use your best grammar—even for error messages. Use full sentences with periods. Keep sentences under 30 words when possible. Cut out the wordiness: don’t say utilize for use; due to the fact that for

because; in order to for to; as well as for and. Use common nouns after command, directory, file, API, or other

object names. – For example, say “Use the BaseException class to render messages,” not

“Use BaseException to render messages.” Don’t omit articles (a, an, or the). Spell out uncommon abbreviations and acronyms. Use consistent terminology across the library, the messages, and the

rest of the UI.

35


Say the same thing in the same way—every time

There’s lots of repetition in error messages, so give your translator a break and use the same sentences or phrases when possible.

For example, use “Contact Software Support” rather than “Contact your support representative” or “Contact support.”

Use boilerplate text for advice about searching databases or websites, getting help, doing common tasks, etc.– Work with your teams to create standard phrasing and use it consistently.

36


Provide complete information for log files and other components

If you ask users to review log files, tell them where to look in the directory structure, what to look for in the log, and what to do with that information.– Bad: See the log file for more information about the documents that the

parser dropped. After you resolve the problem, restart the parser.

– Good: See the index log file index.log in the productX/omnifind/logs directory. Look for dropped documents. After you reformat the dropped documents, restart the parser by running the following command: esadmin start parser

If you tell users to verify, check, or ensure various components are running, working, and so on, also tell them how to do those tasks unless those tasks are really easy.

37


Java exceptions

Avoid the term exception unless the user is a Java programmer and the programmer must know that an exception occurred.

Remember too that an exception in Java is not the same as an error.

In Java, errors are unrecoverable, which means the problem must be fixed before the user can continue.

Exceptions describe events that might disrupt normal operations but won’t stop the application.– Bad: An exception was thrown.

– Good: The server to stopped, and the following exception occurred: {0}

– Or for nonprogrammers: The server stopped. Restart the server by using the following command: esadmin start server server_name

38


Return codes or reason codes

Avoid codes if possible.– Codes make it harder for users to find the resolution to a problem.

– Codes can’t always be easily searched.

Provide a description of the return or reason code if it is included in the message.

Avoid forcing users to look elsewhere for an explanation of the code.– If there are too many return codes to include in the message, refer users

to a separate topic that describes the return codes.

39


Quizzes

Take at your own risk! (These quizzes are incredibly difficult!)

Take the quiz in slideshow mode.


Correct the problems with the message short text.

1. The indexer could not be started. The user may start the indexer from the admin UI once the parser has been stopped.

Correct: The index processing cannot be started. You can start the index processing from the administration console after you stop the parser.

Changed the ambiguous may to can, fixed the illegal term admin UI, changed the ambiguous once to after.

41


Correct the problems with the message short text.

2. The database update failed because you did not start the db service.

Correct: The database cannot be updated because the database service was not started.

The original message blames the user. How unkind! db is likely short for database.

42


Correct the problems with the message text.

3. Internal Error - invalid AutoLinkSMS code.

Correct: The code for the AutoLinkSMS is not valid.

The original message text is a fragment (incomplete sentence) and is difficult to translate. Adding internal error doesn’t help users either. Of course, you’d go on to say why it’s not valid and how to fix the problem.

43


Correct the problems with the message explanation.

4. The {0} dictionary file cannot be closed.

Explanation: Because of an unexpected error, the specified dictionary could not be closed.

Correct: Explanation: The dictionary file cannot be closed because the parser might not be running or the file does not have read permission.

The phrase Because of an unexpected error is vague and unhelpful. Avoid the phrase unexpected error/exception.

44



5. The {0} table was not found for the {1} schema.Explanation: The discovery process could not find the table.

Correct: Explanation: The discovery process cannot find the correct table for the specified schema. If the tables are not found, the table columns cannot be updated when you start the xyz application.

The incorrect explanation simply repeats the first sentence of the message. What’s the point in that? The corrected explanation explains the consequences of not fixing the problem.

45



6. The version configuration update failed.

Explanation: The version configuration update returned an error indicating that a failure occurred.

Correct: Explanation: The update failed because of one of the following reasons: The xx service was not started, the database server is not running, or the response file is not complete.

The incorrect explanation restates the previous sentence without adding anything new. The correct explanation explains the possible reasons for the problem. The user response part of the message would then provide solutions for each problem.

46


Correct the problems with the user response.

7. The {0} dictionary file cannot be closed.Explanation: …

User response: Contact Support.

Correct: User response: Ensure that the dictionary file has read permission and that the parser service is running. To start the parser service, enter: start parserservice

Don’t ask users to call Support unless those users have no way to fix the problem. Ask them to check other product components, files, or services first. If needed, you can add another sentence such as “If the problem persists, contact XYZ Support.”

47



8. The {0} table was not found for the {1} schema. The discovery service cannot be started.Explanation: …

User response: See the log files. Then, start the discovery service.

Correct: User response: Ensure that the table is specified in the schema. You can view the list of schemas and tables in the administration console by clicking View > Schemas. Then, start the discovery service by entering the following command: start discovery

If the directory service does not start, review the xyz.log file in the C:\Program Files\xyz\logs directory for other errors. Look for errors about the schema.

The corrected user response provides more specific details about how to fix the problem.

48



9. The crawler cannot extract or crawl the archive {0} file.Explanation: …

User response: Ensure that the file type is supported.

Correct: User response: Verify that the file specified by the document ID is correct and that it is a supported archive file type such as ZIP, TAR, or GZIP. Also, verify that the file has the correct, supported extension. [Add a link to the topic that covers supported file types.]

The correct user response provides specific information about what file types are supported. The user can take the link or cross-ref to the additional documentation.

49


No more quizzes.

The end.

Yay!

50

Writing Effective Messages - Michelle Carey

Marketing

Transcript of Writing Effective Messages - Michelle Carey