What "voice" should messages and documentation be written in?

Question

I was writing some error/warning messages a while ago, for an application I am developing, and I was thinking - what "voice" do you write software text in, in general?

There's several different categories of text that is included with software packages, including:

• Interface text - very small amounts of text like "OK", "Cancel", "Title:", "n results found", etc.
• Messages - including errors and warnings, such as "You have entered an invalid query.", "Unable to process the file.", etc.
• Code documentation - "Returns the number of rows returned by the query.", "Creates a new top-level window."
• End-user documentation (help!) - "To change the database password, select 'change password' from the file menu. Then enter the current (old) password and the one you wish to change it to."

My question is: what voice should you use when writing text for different areas of software? Would you phrase an error message such as:

• "Please enter a search query."
• "You have not entered a search query."
• "No search query entered."
• "You have entered an incorrect < something >. Please try again."

Do you address the user directly? Do you nicely ask them to try a different approach? ("please try again", "please enter an phrase without any numeric characters")

Personally, I tend to phrase messages so that they address the user and sometimes offer advice at the end "please do some action". I'm a bit inconsistent on that front (A Bad Thing), so I'd especially like to hear your opinions on this one. With code documentation I always use a non-addressing current tense voice, such as "Creates a new dialog with the specified title." and help documentation is written as if the manual is speaking to the reader.

Since this is a highly subjective question I've marked it community wiki. I'm very interested on what rules and guidelines you or your organization uses when writing text, messages and forms of documentation for your software.

If any part of my question is unclear, I'm sure you'll let me know, and I'll be sure to fix it. ;)

Answer 1

Among the four variants you listed:

* "Please enter a search query."
* "You have not entered a search query."
* "No search query entered."
* "You have entered an incorrect < something >. Please try again."

the first and the fourth address the user - they explictly tell him that the program can't continue until the user does some specific action (that he hopefully understands how to do).

The second and the third just say "something hasn't happened". The user feels "emm... it wouldn't work... what do I do?" That's not good.

The user is there because he wants to accomplish a task. The software should guide the user if something goes wrong, not state "error, I will not work work until some matter not mentioned herein fixes that".

Answer 2

Saying Please helps users differentiate between stuff they did wrong and stuff we devs did wrong, which saves us a lot of bug reports. It also has the nice side-effect of making them feel good about the software, even when it's tricky to use. Since there's often a fractious relationship which often exists between devs and business, Please is just gold. Use it liberally.

Answer 3

Firstly, in your example you are validating user inputs. Using a dialog to report problems after users have filled in a complex form, and then requiring the user to work out which field was wrong is a very old school and unfriendly approach. It's easy to validate most fields as the user types and show (e.g.) a warning icon next to the field, which can be clicked on to get details about what is wrong. This allows the user to verify that they have entered the correct information as they complete each field, and avoids a "wall" being thrown in their face if they got something wrong.

Seek to guide rather than punish

Once we have got to the point where we need a dialog, then the Windows 7 UX (user experience) guide has some good advice.

Essentially, the basics to remember are to be friendly and factual:

• Use a friendly, polite, casual tone ("can't" rather than "cannot"). Use simple short words, brief descriptions, and avoid technical jargon that the user may not know - stick to their domain knowledge rather than yours. "Please enter your WiFi password" is better than "Enter your 64-bit WEP PKA key".

• Try to keep things positive and help the user to move forward, rather than giving negative reviews of their past performance. Don't use words like "error", "fatal", "failed", etc, as they have strong negative connotations. i.e. don't say "Error: Validation failed: Speed must be greater than zero". (This particular example should be phrased as helpful information rather than an "error" anyway).

• Don't address the user as "you", and don't blame them for the problem. i.e. "Speed must be greater than zero" rather than "You didn't enter a valid speed" or "You must enter a speed greater than zero", or the rather curt and uninformative "Invlaid speed". Personal address "lays the blame" on the user, whereas simple facts allow you to helpfully guide them to the right result.

• Don't refer to the application as "I", and don't apologise: "I can't load file xyz", "Sorry, xyz can't be loaded". The computer is not a person, and isn't the user's best friend. Just be factual and informative: "File 'xyz' can't be loaded because it's not in one of the supported formats (jpeg, gif, bmp)."

• Windows 7 uses Task dialogs which have a title, a description and an icon. This allows you to summarise the report so that advanced users can quickly understand and correct the problem, while the description can explain how a less advanced user can go about fixing the problem. (e.g. "Database not found", "Please check that database 'xyz' exists on server 'abc', and that you have sufficient permissions to access it". The icon allows you to indicate the difference between information, warnings (things the user may need to check, but which won't necessarily be a problem, and errors (things that must be corrected before the user may continue)

• When reporting, give the user the information they need to understand the problem and help them to rectify it. i.e. "Error" and "Module load failed" are terrible messages because they give the user no useful information and simply induce terror, even in many advanced users. Tell the user what went wrong, and include information to help them locate and correct the problem.