Chapter 8. Writing for diverse audiences
Apply the following guidelines to make information clear and accessible to everyone.
Accessibility
Accessibility is the successful access to information technology and its supporting documentation by people who have disabilities, such as people with visual impairments and people who cannot use a traditional keyboard. When you design or modify information to allow access by the greatest number of people, you make it accessible.
The following accessibility guidelines are based on the US Standards for Electronic and Information Technology, developed by the Access Board for Section 508 of the US Rehabilitation Act, Worldwide Web Consortium (W3C) recommendations, and IBM research:
• To ensure that all users can access documentation, provide documentation in an accessible format. If you provide documentation in multiple formats, at least one of the formats must be accessible. For example, hardcopy information is not accessible because some visually impaired users cannot read it. Because screen reader support for HTML is more robust than it is for other formats, HTML is the preferred format for accessibility.
• Provide a topic or section that describes all the accessibility features that are available in the documentation and in the product:
• Indicate which documentation format is accessible and indicate how and where users can access that format.
• Describe accessibility features of the documentation, including ways to navigate the documentation, any unique keyboard commands that are needed to access documentation, and information about accessible syntax diagrams, if they are provided.
• Document unique keyboard accessibility features in the product. You do not have to document standard operating system keyboard shortcuts.
• If you provide instructions for completing tasks by using the mouse, also include the instructions for doing those tasks by using the keyboard if the keyboard instructions involve nonstandard operating system keyboard shortcuts.
• Document preferences that the user can enable in the product to enhance accessibility.
• If your information includes an index, create index entries for keyboard shortcuts, preferences, and any other accessibility features under both the feature name and under a main (i1) entry of accessibility.
• Provide a short text alternative for all graphic images by using the <alt> element. If a graphic is adequately described in the surrounding text or is used for formatting purposes only, include an empty <alt> element. An empty <alt> element causes most screen readers to ignore the image, whereas a missing <alt> element causes the screen reader to read details of the image (file name and size, for example). Alternative text for icons should indicate the function that the icon performs, not describe its appearance. If the short text alternative is not sufficient, provide a long description in addition to a short text alternative. The following example shows a graphic image that requires short alternative text and an additional long description:
Alternative text
Pie chart that depicts percentage of sales across geographic regions
Long description
Sales across geographic regions are as follows: North America, 45%; Asia Pacific, 30%, Europe, 17%, Latin America, 8%.
• Provide accessible syntax diagrams, where applicable. Standard graphic railroad syntax diagrams are not accessible to someone who is using a screen reader. In addition to providing railroad syntax diagrams, provide syntax diagrams in dotted decimal format or BNF (Backus-Naur) format. The following example shows a railroad syntax diagram:
The following example shows the same syntax diagram in dotted decimal format, which can be read by a screen reader:
• Do not use color or contrast as the only way to convey meaning. For example, using red text as the only way to indicate an error condition is not accessible.
• Make tables more accessible by defining column headers and row headers and by including a caption. Row and column headers enable screen readers to provide information about the relationship of data cells in a table. Table captions provide an overview of the contents of the table. Refer to the documentation for your authoring tool to determine how to apply these accessibility aids to your tables.
For more information, see Developing Quality Technical Information, Chapter 10, “Ensure that all users can access the information.”
International audiences
The audience for IBM information includes native English-speaking users, users whose primary language is not English, and users who do not speak or read English but, instead, rely on information that was translated from English into another language.
Follow the guidelines in this topic to ensure that your information is clear for all types of audiences.
Style
Apply the following style guidelines when you write for an international audience:
• Keep sentences as short and simple as possible. Try to keep sentences to 25 or fewer words.
• Avoid slang, jargon, humor, sarcasm, colloquialisms, idioms, emoticons (also called smilies), and metaphors.
• Be succinct. Avoid redundant and unnecessary text.
• In general, use a complete sentence to introduce a list. You can introduce procedures with a sentence, an infinitive phrase, or a heading.
• Make list items grammatically parallel. For example, do not use a mix of phrases and sentences or a mix of passive and active voice in the same list.
• Do not use contractions. For example, use do not instead of don’t.
• Do not overuse abbreviations and special characters.
• Do not use symbols instead of words in running text. For example, do not use an ampersand (&) or a plus sign (+) to mean and.
• Avoid negative constructions.
• Avoid using please and thank you. Technical information requires an authoritative tone; terms of politeness convey the wrong tone for technical information and are not regarded the same way in all cultures.
• Do not write dates only in numerical form. In most countries, a date written as 9/12/99 means 9 December 1999, not 12 September 1999.
Grammar
Apply the following grammar guidelines when you write for an international audience:
• Write in active voice and the present tense as much as possible.
• Avoid using a phrasal verb (verb and a preposition) if the verb alone provides the same meaning.
• When you use a verb phrase that begins with a present participle, such as creating, or past participle, such as created, at the beginning of a sentence, make sure that the verb phrase modifies the correct word. Failure to do so can result in a dangling modifier.
• Make the subject of a sentence clear. For example, avoid ambiguous pronoun references in which a pronoun can refer to more than one antecedent.
Similarly, avoid using expletive constructions such as it is, there are, and there is, which hide the subject of the sentence.
• Avoid using long noun phrases. Limit a noun phrase to no more than three words. When you use a noun phrase, make sure that it has only one meaning and that you use it consistently.
• Do not omit the word that from clauses. The use of the conjunction that, although technically optional in some sentences, is never wrong and makes the sentence easier to translate and clearer for readers whose primary language is not English. For example, write “Verify that your directory service is working” instead of “Verify your directory service is working.”
• Avoid using too many prepositions in a sentence. For example, you can rewrite “The report is a list of the current status of all of the event monitors for this process” as “The report lists the current status of all event monitors for this process.”
• Do not omit articles and prepositions that can increase the clarity of a sentence. For example, rewrite “Unload the file using the ULOAD utility” as “Unload the file by using the ULOAD utility.”
• Avoid using the same word for different parts of speech. In particular, avoid using words that primarily function as verbs as nouns or adjectives. For example, in English, the word install is a verb. Therefore, instead of writing “during the install,” write “during the installation,” and instead of writing “the install job,” write “the installation job.” Other verbs that are commonly misused as nouns or adjectives include configure, compile, debug, and fix. Note that the same form of some words can legitimately function as different parts of speech. If you are in doubt about which part of speech a word can be used as, consult a dictionary.
• Use simple and clear coordination so that the reader can tell what the relationships are between the elements of a sentence. For example, “the file or result field definition” can have any of the following meanings:
• The result-field definition or the file
• The file definition or the result-field definition
• The file-field definition or the result-field definition
• The definition of the file or of the result field
• The field definition of the file or of the result
• Make sure that the elements of a sentence are parallel. Words, phrases, and clauses should be grammatically equal.
• Avoid ambiguity when you have more than one infinitive within a sentence. For example, the following sentence is ambiguous: “Use the utility to run maintenance activities and save your maintenance settings.” This sentence can be interpreted in two ways:
• Use the utility to run maintenance activities and to save your maintenance settings. (The utility does both steps.)
• Use the utility to run maintenance activities, and then when you are done, save your settings. (The process consists of two separate steps, only one of which is done by the utility.)
Rewrite the sentence to clarify which of the two interpretations you intend. For example, if the utility does both steps, include the preposition to before each of the infinitives: “Use the utility to run maintenance activities and to save your maintenance settings.”
• When you write a sentence that includes two coordinate clauses, do not omit the verb from the second clause.
Terminology
Apply the following terminology guidelines when you write for an international audience:
• Use correct and consistent terminology.
• Minimize the creation of new terms.
• Use the simplest term possible to convey the intended meaning. For example use large instead of voluminous, and use small instead of diminutive.
• Define product-specific terms or terms used in a special way in a product glossary, or explain them in the text.
• Avoid culture-specific references that might not be widely understood, such as holidays and celebrations, monetary units, and phone number and address formats.
• If your product uses the # symbol, in most cases refer to it as the number sign (#), and explain clearly how it is used.
• Be selective when you use terms that have different meanings in different environments. For example, use conversion for systems or programs, but use translation for national languages.
• Avoid using the terms billion and trillion because they have different meanings in different countries. Use the number instead.
• Avoid using the terms domestic and foreign.
• Do not use Latin abbreviations, such as e.g., etc., and i.e.
• Vary the use of proper names in documentation. Use names that represent a variety of ethnic backgrounds, genders, and locations.
• Do not use made-up terms in examples, for example, didget and gidget. Use terms that can be translated and understood.
• Avoid terms that might be misinterpreted. For example, use once to mean one time, not to mean after or when. Use since in relation to the passing of a period of time, not as a synonym for because.
For definitions and usage advice for specific terms, see “Word usage” on page 300.
Punctuation
Apply the following punctuation guidelines when you write for an international audience:
• In general, do not use forward slashes between words to mean “and/or”; a forward slash can be ambiguous. Rewrite the sentence to clarify the meaning. For example, use “Insert the CD or DVD” instead of “Insert the CD/DVD,” and use “You can select green, blue, or both” instead of “You can select green/blue.”
• Use commas between three or more items in a series, including before the conjunction that introduces the last item, to ensure that readers can clearly separate the items. For example, write “Such functions include storage management, program management, and security.”
• Do not form a plural by adding (s). Try to rewrite the sentence to use either the plural form or singular form, whichever is more appropriate. If you must indicate both forms, repeat the noun, or use one or more. For example, instead of writing “enter the registration number(s),” write either “enter the registration number or numbers” or “enter one or more registration numbers.”
• Do not use em dashes in technical information. More common punctuation marks, such as commas, parentheses, or a colon, provide the same result. Rewrite the text or use different punctuation.
Exception for marketing content: Em dashes are acceptable in marketing content. For details and examples, see “Exceptions for marketing content” on page 274.
Graphics and images
Apply the following guidelines when you use graphics and images in information for an international audience:
• Be careful not to use colors, symbols, and text in a way that some cultures might find confusing or offensive:
• Colors have different connotations in different cultures. For example, in some Eastern cultures, red is used to convey good luck; however, in many Western cultures, red is used to convey danger or alarm.
• Similarly, many symbols, such as those of body parts and of animals, have culturally specific connotations. For example, hand gestures that convey a positive meaning in some cultures are offensive in other cultures.
• Icons that are based on English words present translation challenges. For example, using the letter B to indicate bold text is difficult to translate because B does not have the same meaning in most languages.
• Consider the implications for images in information that will be translated into a bidirectional language such as Arabic or Hebrew:
• Be careful about how you refer to left and right arrows or any other directional reference in text that is associated with a directional graphical image. When possible, use words such as start, end, next, or previous instead of right or left.
• Images are often flipped so that the resulting image is a mirror image of the original. Flipping some images, such as geographical maps or corporate logos, is generally not appropriate and needs special handling. Additionally, image maps can be corrupted if individual images within the image map are flipped.
• Do not use national flags:
• The Paris Convention for the Protection of Industrial Property explicitly prohibits the use of national flags as trademarks.
• The use of a flag might be falsely interpreted as an expression of approval or sponsorship of that country or as an affiliation with that country.
• Some countries are particularly sensitive about how and in what context their flags are displayed.
• International misunderstandings that are based on border misrepresentations and other inaccuracies can have and have had major implications for companies that used maps.
• Be careful about using geographical maps:
• International misunderstandings that are based on border misrepresentations and other inaccuracies can have and have had major implications for companies that used maps.
• Geographical information, such as national or internal political boundaries, the names of countries, states, and cities, and the names of other geographic elements, continually changes. Maps that include explicit details might have to be updated regularly.
• Translation of map content presents additional challenges. In some cases, substituting a similar foreign language map in place of an English language map might be sufficient. If you work with maps in your documentation, consult your geographic specialist to determine the most appropriate course of action.
For more information about writing for translation, see Developing Quality Technical Information, Chapter 11, “Applying quality characteristics to information for an international audience.”