Chapter 7. Computer interfaces

Document computer interfaces in an accurate, clear, and consistent way to make it easier for users to meet their goals.

Commands

Apply the correct capitalization and fonts to commands, their parameters, and their options (the values of parameters). Show the syntax of commands, and explain the meanings of the parameters and options.

Capitalization

If the command language is case sensitive, show the commands, parameters, and options as they must be entered from the console, terminal, or keyboard. If the command language is not case sensitive, show the commands, parameters, and options in lowercase. If you write information for multiple operating systems and the command language is case sensitive on one operating system but not on the others, show the commands, parameters, and options in the case-sensitive form.

Commands, parameters, and options in running text

In running text, use a bold monospaced font for a command. If a parameter or option is a variable value, use an italic monospaced font; otherwise, use a bold monospaced font for the parameter and a monospaced font for the option.

When you refer to a command, parameter, or option in running text, specify the word command, parameter, or option after the name. Command, parameter, and option names are not translated, so without the identifying noun, users might be confused about what the name represents. Alternatively, refer to a command, parameter, or option by using a lowercase descriptive phrase, such as one that includes an adjective and a noun.

Do not use a command name as a verb. Using command names as verbs can cause problems for translation.

Commands, parameters, and options in instructions

To instruct users to enter commands, use type, enter, or issue. Use one term consistently throughout your information. To refer to the area where you enter commands, in documentation for only Windows operating systems, use command prompt. In documentation for other operating systems or for both Windows and other operating systems, use command line. Do not use run to refer to specifying a command on a command line or at a command prompt. However, you can use run to refer to the general use of a command.

When you tell users to type, enter, or issue a command on a command line or at a command prompt, use a monospaced font for the command name. If a parameter or option is a variable value, use an italic monospaced font; otherwise, use a monospaced font.

Do not use the word command after the name of the command.

If users must enter a command, its parameters, and its options on one line but you cannot show that in the documentation because of a lack of space, explain the requirement in the introductory text.

For information about creating reference topics for commands, see DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Chapter 4, “Reference topics.”

Command syntax

To specify simple command syntax, such as in task topics, use text. To specify complex syntax, such as in reference topics, use syntax diagrams (also referred to as railroad diagrams) if your authoring tool supports them; otherwise, use text.

Using text to specify command syntax

Follow these guidelines to specify syntax by using text:

• If necessary, explain the syntax conventions in your documentation. For example, in a book, include the explanation of syntax conventions in the preface or in an introductory chapter.

• Use a monospaced font for a command name. If a parameter or option is a variable value, use an italic monospaced font; otherwise, use a monospaced font. If you must use a multiple-word variable name, remove the spaces between the words, or connect the words with underscores.

• Use vertical bars to separate alternative values.

• Enclose optional items in square brackets.

• Underline default parameter values.

Explain the meanings of items in the syntax immediately after showing the syntax:

• Be consistent in explaining both the parameters and options or explaining just the options.

• Optionally, use the word where, with a lowercase w, to introduce the explanations.

• To explain multiple items, consider creating a vertical list for better readability by using the following guidelines:

• Unless you are limited by your authoring tool, use a simple list or definition list for a main list, and use an unordered list or definition list for a nested list, as shown in the examples. If your authoring tool prevents you from using these types of lists, use a different but clear and consistent format.

• If you introduce a list with the word where, use a colon after where.

• Use a consistent style for descriptions:

• If you use a definition list, start all descriptions with a full sentence, or start all descriptions with a sentence fragment. If you use sentence fragments, start each one with the third-person form of a verb, or start each one with a noun phrase. Start each description with an uppercase letter.

• If you use a simple list or unordered list, start all descriptions with a sentence fragment that starts with the third-person form of a verb and a lowercase letter.

• Unless your authoring tool imposes a different standard, use a bold monospaced font for parameters and a monospaced font for options, except for variable values. Use an italic monospaced font for variables.

• Optionally, use text to indicate whether an item is required, optional, or the default. Use consistent wording.

Using diagrams to specify command syntax

Syntax diagrams visually represent command syntax. An example of a syntax diagram follows.

                           .-,--------------.
                           V                |
>>-LOAD--+--------+--FROM----+-filename---+-+--OF--filetype----><
         '-CLIENT-'          +-pipename---+
                             '-devicename-'

Important: Because syntax diagrams are inaccessible to users of screen readers, you must also provide an alternative accessible format. Both the dotted decimal format and Backus-Naur Form (BNF) are accessible by screen readers.

Follow these guidelines to specify syntax by using a syntax diagram:

• Explain the syntax conventions in your documentation. For example, in a book, include the explanation of syntax conventions in the preface or in an introductory chapter. In topic-based information, provide a topic about command-syntax conventions.

• Use the following basic components in the syntax diagram. If your authoring tool supports syntax diagrams, see the tool documentation for detailed information about how to create these components.

• Use two right-facing arrowheads and a dash (>>-) to indicate the beginning of a syntax diagram. Use a dash, a right-facing arrowhead, and a left-facing arrowhead (-><) to indicate the end of a syntax diagram. If you cannot show all the syntax on a single line, use a dash and a right-facing arrowhead (->) to indicate that the syntax is continued on the next line. Use a right-facing arrowhead and a dash (>-) to indicate that the syntax is continued from the previous line.

• Put required items on the main path. The following diagram shows that the db2idrop command name is required.

>>-db2idrop----------------------------------------------><

• Put optional items below the main path. The following diagram shows that the SHOW DETAILS parameter is optional.

>>-LIST INSTANCE--+--------------+-------------------------><
                  '-SHOW DETAILS-'

• Put choices in a stack. If users must choose at least one of the items, put the first item in the stack on the main path. The following diagram shows that users must choose between the on and off parameters.

>>-db2iauto--+-on--+---------------------------------------><
             '-off-'

If users do not have to choose any of the items in a stack, put the entire stack below the main path. The following diagram shows that users can specify the BACKUP parameter, the ROLLFORWARD parameter, or neither parameter.

>>-LIST HISTORY--+-------------+---------------------------><
                 +-BACKUP------+
                 '-ROLLFORWARD-'

If one of the items in a stack is the default, put it above the main path. The following diagram shows that verbose is the default parameter.

             .-verbose-.
>>-db2sampl--+---------+-----------------------------------><
             '-quiet---'

• Use a monospaced font for a command name and for parameters and options that are not variable values. For variable values, use an italic monospaced font. If you must use a multiple-word variable name, remove the spaces between the words, or connect the words with underscores. The following diagram shows that users must provide a database name and can optionally specify an alias name.

>>-CATALOG--+-DATABASE-+--dbname--+-----------+------------><
            '-DB-------'          '-AS--alias-'

• Indicate that users can specify an item more than once or can specify more than one item by using an arrow above the main path that returns to the left. The following diagram shows that users can specify a file name, pipe name, or device name multiple times. The separator for multiple or repeated values, if required, is shown on the arrow. In the example, each name must be separated by a comma.

              .-,--------------.
              V                |
>>-LOAD FROM ---+-filename---+-+---------------------------><
                +-pipename---+
                '-devicename-'

Explain the parameters and their options after the syntax diagram, as follows:

• In general, describe the parameters and their options in the same order in which you display the parameters and their options in the syntax diagram. However, if the order of parameters is not significant for the command and the parameters are numerous, alphabetize the descriptions to improve retrievability.

• Use a definition list to specify the parameters and options and their descriptions, unless there are multiple options for a parameter. If a user can specify multiple options for a parameter, specify those options and their descriptions in a nested definition list or nested unordered list.

• Unless your authoring tool imposes a different standard, use a bold monospaced font for parameters and a monospaced font for options, except for variable values. Use an italic monospaced font for variables.

• Use a consistent style for descriptions in a particular list:

• If you use a definition list, start all descriptions with a full sentence or with a sentence fragment. If you use sentence fragments, start each one with the third-person form of a verb or with a noun phrase. Start each description with an uppercase letter.

• If you use an unordered list, start all descriptions with a sentence fragment that starts with the third-person form of a verb and a lowercase letter.

• Use an underscore and, optionally, text to indicate default values.

• Optionally, use text to indicate whether an item is required or optional, using consistent wording.

For more information about documenting command syntax, see DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Chapter 4, “Creating syntax diagrams: <refsyn> and <syntaxdiagram>.”

Programming elements

For programming keywords (sometimes referred to as reserved words), such as SQL statements, APIs, and Java methods, use the correct capitalization, identify the type of keyword, and use the correct part of speech. For programming variables, use appropriate names.

For information about commands, see “Commands” on page 185 and “Command syntax” on page 187.

Keywords

Follow these guidelines when you refer to keywords:

• For programming languages that are case sensitive, spell keywords as required by the programming language syntax. Otherwise, use uppercase for keywords.

• Specify the keyword type after the keyword. Keywords are not translated, so without the keyword type, users might be confused about what the keyword represents. Alternatively, refer to the keyword by using a lowercase descriptive phrase, such as one that includes an adjective and a noun.

Some keywords incorporate a keyword type as part of the name. Even if a keyword type is included as part of the keyword, specify the keyword type after the keyword, or refer to the keyword by using a lowercase descriptive phrase.

• Do not use a keyword as a verb, and do not add a verb ending to a keyword other than a Boolean operator such as AND or OR. Using keywords as verbs can cause problems for translation.

Variables

If the programming language interface has specific names for variables, such as DataInfoLength, use those names. Otherwise, for a non-numeric variable, use a short, descriptive word in an italic font, such as filename. For a numeric variable, use a short, descriptive word in an italic font, such as max, or a single letter, such as n. If there are variations on the same type of variable, you can follow the word or letter with a number, such as max1, max2, and so on or n1, n2, and so on.

For information about creating reference topics for programming elements, see DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Chapter 4, “Reference topics.”

Code and command examples

Where necessary for clarity, use examples to help show how to write code and use commands. Present code and command examples clearly and consistently.

Follow these guidelines for code and command examples:

• Use examples to support text, not replace it. Do not expect users to extrapolate instructions from examples.

• Use a monospaced font to show examples. To emphasize a new or changed line, you can use a bold monospaced font. To make it easier for users to follow the flow of an example, consider using indentation.

• Use a complete sentence to introduce an example or the results of running an example. Do not start a sentence before an example and continue the sentence after the example. End the sentence with a colon unless other sentences intervene between the introductory sentence and the example; in that case, end each sentence with a period.

• Use a consistent approach for captioning examples. You might choose to show large examples as figures, with appropriate captions, and embed small examples within the text, without captions. If you use captions, use informative ones that help the reader to identify the examples in the table of contents.

• If you indent examples, use a consistent approach.

• If a user must enter code or a command on one line but the example does not fit on one line in your output, explain that in introductory text. If the example is from software that uses continuation characters, show the example exactly as it is displayed in the program.

For more information about including examples in documentation, see the following topics:

• DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Chapter 2:

• “Providing an example of a step: <stepxmp>”

• “Describing an example that helps users complete the task: <example>”

• Developing Quality Technical Information, Chapter 6:

• “Choose examples that are appropriate for the audience and subject”

• “Use focused, realistic, accurate, up-to-date examples”

• “Make examples easy to find”

• “Make code examples easy to adapt”

• “Set the context for examples and scenarios”

Data entry on the command line

Use specific terminology when you tell users to provide data. Highlight that data in a monospaced font, and explain clearly how to provide that data.

Follow these guidelines:

• In documentation for only Windows operating systems, use command prompt. In documentation for other operating systems or for both Windows and other operating systems, use command line.

• To instruct users to provide data on the command line or at the command prompt, use type or enter. If users can provide data in several ways or can use a method other than a keyboard to provide data, such as voice-activated software, consider using specify.

• Use a monospaced font for the data that users provide.

• Spell and capitalize data the same way that the user must provide it.

• If the data includes a variable, show the variable in an italic monospaced font. Explain immediately afterward what the variable represents. Unless you are limited by your authoring tool, use an italic monospaced font for the variable in the explanation. Optionally, use the word where, with a lowercase w, to introduce the explanations.

• To explain multiple items, consider creating a vertical list for better readability by using the following guidelines:

• Unless you are limited by your authoring tool, use a simple list or definition list, as shown in the examples. If your authoring tool prevents you from using these types of lists, use a different but clear and consistent format.

• If you introduce a list with the word where, use a colon after where.

• Use a consistent style for descriptions:

• If you use a definition list, start all descriptions with a full sentence, or start all descriptions with a sentence fragment. If you use sentence fragments, start each one with the third-person form of a verb, or start each one with a noun phrase. Start each description with an uppercase letter.

• If you use a simple list, start all descriptions with a sentence fragment that starts with the third-person form of a verb and a lowercase letter.

• If users might mistake the punctuation for part of the data to enter, rewrite the sentence.

File names, file types, and directory names

Use correct capitalization, highlighting, punctuation, and grammatical constructions when you refer to file names, file name extensions, file types, and directory names. A file type is a word or uppercase abbreviation that indicates the kind of file, such as PDF. A file name extension is the portion of a file name that follows the dot, such as exe in install.exe.

Follow these guidelines:

• Use lowercase for file names and directory names for operating systems and application programs that are not case sensitive. For a case-sensitive operating system or application program, use the capitalization that is used in the operating system or application program. Highlight file names, file name extensions, and directory names in a monospaced font.

• When you refer to a subdirectory by using a full path name, such as /usr/bin/samples, use a forward slash (/) or backslash () according to the convention of the operating system. For information that applies to multiple operating systems, be consistent and describe the convention if necessary.

• If a path does not fit on one line, end the first line after an existing forward slash or backslash, and continue the path on the next line. Do not add a hyphen to indicate a break in a path.

• To express part of a path name as a variable, use a short, descriptive word in an italic monospaced font.

• Include the period in a file name extension. Assume that the period is pronounced as dot, and use the indefinite article a.

• Do not use a file name, file name extension, file type, or directory name as a noun. Instead, use the file name, file name extension, file type, or directory name as an adjective in one of the following ways:

• Follow the file name, file name extension, or file type with the word file, and follow the directory name with the word directory, as shown in the first four correct examples.

• Use the file name, file name extension, file type, or directory name alone as shown in the last four correct examples.

• Avoid placing the noun file or directory before the name of the file or directory. Instead, use the name as an adjective, followed by the noun file or directory.

• Define the abbreviation for a file type on first use if the abbreviation is not commonly known to the target audience.

Graphical user interface elements

Use specific capitalization, spelling, and wording to refer to graphical user interface elements.

Location of interface elements

When you refer to the location of an element in an interface, use the following terms:

• For nouns, use the terms upper left, upper right, lower left, and lower right. Do not use left hand or right hand.

• For adjectives, use the hyphenated terms upper-left, upper-right, lower-left, and lower-right. Do not use left-hand or right-hand.

To conform to accessibility best practices, do not rely solely on positional information about components in an interface. People with visual impairments might not be able to understand information if you convey it only by location; provide additional text.

Interface element labels

Follow these guidelines:

• When you write about an item that is displayed in a graphical user interface, match the capitalization and spelling of the item in your writing. For example, if a label is displayed with initial uppercase letters or all uppercase letters, write the label the same way in the documentation. However, if the text in the interface contains a spelling mistake, use the correct spelling in the documentation, and have the mistake corrected.

• In documentation, do not include punctuation in a label, such as an ellipsis that indicates that more information is required from the user, unless one of the following conditions applies:

• The omission of the punctuation would result in confusion over the meaning of the interface element.

• You are using a tool that extracts the wording on the label, including the punctuation, for use in the documentation.

• Use one of the following approaches when you refer to an interface element:

• For some interface elements, as shown in the table in this topic, use the label, title, descriptive name, or name that is indicated by the tooltip, followed by the type of the interface element.

• For other interface elements, as shown in the table in this topic, use only the label, title, descriptive name, or name that is indicated by the tooltip. However, if an interface contains elements with the same label or very similar labels, include the element type to ensure clarity. If you refer to a button as a button, you must distinguish the type of button, such as a push button or radio button.

• For all elements, if users clearly know which element to use, use only the type of the element, or tell users to perform the action without using the label, title, descriptive name, name that is indicated by the tooltip, or type.

• Do not use a label as a generic noun or verb.

• For graphical items such as push buttons or icons, if users would benefit from seeing the graphic, include it after the label or tooltip name.

Usage and highlighting for user interface elements

Use the guidelines in the following table to refer to specific types of user interface elements.

Menu instructions and navigation

Use specific wording and formatting to instruct users to navigate through menus, navigation trees, or directories. The wording in the instructions can differ for experienced and novice users.

Menu instructions

Use the following guidelines when you instruct users to use a menu:

• Refer to the choices on a menu as menu items.

• When you specify which item to select from a menu, use the format that is appropriate for your audience. For experienced users, use the format in the following example:

For novice users, use the format in the following example:

• To separate menu choices, use the symbol that your authoring tool provides. If a symbol is not provided, use the greater than symbol (>), and insert a space on each side of the symbol.

• Use bold for menus, menu items, and separator symbols. If a menu contains variable menu items, use lowercase bold italic.

• Do not document punctuation such as an ellipsis that is part of a menu item unless one of the following conditions applies:

• The omission of the punctuation would result in confusion over the meaning of the menu item.

• You are using a tool that extracts the wording of the menu item, including the punctuation, for use in the documentation.

• Consider whether you must explain that a pop-up menu is displayed when users right-click an object or a window. This behavior is widely understood.

• Assume that users know where the Windows Start button is located; do not specify the location of the button.

Navigation trees

In general, use the format in the following example to guide users through a navigation tree. Use bold for the items in the navigation tree and the greater than symbol. Insert a space on each side of the symbol.

If the navigation tree contains variable elements, use lowercase bold italic.

Directories

Use the standard format for menu instructions to instruct users to navigate to directories and files. Use bold for the directory and file names and the greater than symbol. Insert a space on each side of the symbol.

Mouse buttons

Unless stated otherwise, instructions for a mouse apply to right-handed users and the left mouse button. If you must distinguish between the buttons on a mouse, use left mouse button, middle mouse button, and right mouse button.

Use the verbs click, double-click, and right-click to refer to mouse actions. Do not use the preposition on with mouse actions.

To refer to a double-click action with the right mouse button, use the term double right-click.

Keyboard keys

Use the correct verbs and terminology to refer to keyboard keys.

Verbs to use with keyboard keys

Follow these guidelines when you use verbs with keyboard keys:

• For keys that are printed with letters, words, numbers, and symbols and result in output on a screen, use type or enter.

• For keys that perform functions other than producing output on a screen, such as Enter, Esc, Shift, and Tab, use press.

• Do not use the verb depress, hit, punch, or strike.

Key names

Use the following guidelines to refer to key names:

• Use uppercase letters to describe letter keys.

• Do not highlight the names of keys.

• If a key has a symbol printed on it, at first reference, use the descriptive name of the key followed by the symbol in parentheses. For later references, you can use only the symbol if no ambiguity or confusion would result.

• If a key is a Function key (Fn or PFn) or a Program Access key (PAn), use the descriptive name of the key at first reference only if needed for clarity. If you use the descriptive name of the key at first reference, follow the name with the text that is printed on the key, in parentheses. For later references, you can use only the text that is printed on the key if no ambiguity or confusion would result.

• If a key has an abbreviated name printed on it, use the abbreviated name instead of the spelled-out name when the meaning of the abbreviated name is clear.

• Use an article with a descriptive key name but not with an abbreviated name, symbol, number, or letter that is printed on a key.

The following table provides the descriptive names of common keys. Your keyboard might have different keys.

Key combinations

When you write about two or more keys that are used in combination to perform a function, use the plus sign (+) to separate the key names. Do not insert a space before or after the plus sign. If the key that you press is a symbol key, avoid ambiguity by spelling out the name of the key, and follow the key name with the keyboard symbol in parentheses. If you press the same key twice, write the second action in a separate sentence.

In instructions to press a key while clicking the mouse, write “press keyname and click ...”

Messages

Messages must be accurate, complete, and helpful. They must be clearly written, be free from grammar and punctuation problems, and follow style and terminology guidelines. In addition, messages must not blame the user.

Message types

The most common types of messages are as follows:

Error

Use error messages to inform users that a problem in the system or application occurred. Users or systems cannot continue their tasks until the problem is resolved. An example of an error message is The file could not be found.

Warning

Use warning messages to alert users about a condition that might cause problems in the future. Users can generally continue with their tasks, but those tasks might not be completed in a way that is expected. An example of a warning message is The parser could not parse all documents. Some documents were skipped.

Information

Use information messages to provide information about normal conditions and operations. An example of an information message is Updates are being processed.

Confirmation

Use confirmation prompts to ask users to verify an action that the users or sometimes the system initiated. Also, use confirmation prompts to ask users for additional information to complete a step or to ask whether to save information for future use. An example of a confirmation prompt is Are you sure that you want to close your document without saving your changes?

Components of error, warning, and information messages

Most error, warning, and information messages require the following information:

• A message identifier

• Message text

• An explanation

• A user response

The following error message provides a brief description of the problem followed by a complete description of the cause (explanation) and user action (user response).

SRERT0164E: The properties file could not be loaded.

Explanation: The properties file might not exist because it was
removed during an upgrade, or the file might not have read permission.

User response: Verify that the properties file exists in the
MC_HOME/applications directory. If the file is missing, check the
file that you created as a backup image before you upgraded the
system. Also, ensure that the file has read permission.

Message identifiers

A message identifier is a unique alphanumeric identifier that provides a quick way to distinguish messages. Message identifiers help users search for messages in logs, information centers, or message catalogs. All error and warning messages require identifiers. Information messages might require identifiers depending on how and where the messages are displayed in the interface. Confirmation prompts do not typically require identifiers.

A message identifier typically includes three parts: a multiple-character product identifier, a unique number, and a single-character message type identifier. The most common message type identifiers are I for information, E for error, and W for warning.

Message text

The message text briefly describes the problem. Follow these guidelines when you write message text:

• Describe the problem in one or two full sentences. Include only essential, relevant information.

• Focus on the problem. Wording such as “An error occurred” or “An error was encountered” is typically not useful. Provide more specific information.

• Do not use wording that directly blames the user, even if the user caused the problem. If necessary, use passive voice to avoid placing blame.

Message explanations

The message explanation expands on the message text. A message explanation is required for error and warning messages. Some information messages might also require explanations. For error and warning messages, one of the goals of the explanation is to help the user avoid the problem in the future.

Follow these guidelines when you write message explanations:

• Write a clear explanation of the circumstances that resulted in the message. For example, in the case of a warning or error message, provide details about why the problem occurred and the consequences of the error. If an information message does not require an explanation, use the sentence “This message is for informational purposes only.”

• Write a complete explanation but include only necessary and relevant details.

• Do not repeat the message text in the message explanation. Repeating the information is not helpful, especially if unaccompanied by other details.

• Do not blame the user even if the user caused the problem.

Message user responses

The user response describes what the user must do to proceed, for example, to recover from a problem. You must include a user response for all error and warning messages even if the user does not have to do anything. If the user does not have to take any action, use the sentence “No action is required.”

Follow these guidelines when you write user responses that require user action:

• Use active voice and imperative statements.

• Provide specific instructions for correcting or preventing the problem. For example, follow these guidelines:

• Be precise when you refer to files and directories. For example, instead of telling users only to “See the log file,” also specify the name and location of the file and what to look for in that file.

• Tell users the names of the reference elements to use, such as the names of commands and APIs, and consider providing examples.

• Be concise. Provide only necessary technical information.

• If possible, provide all the information that users need rather than referring them to another source of information. However, if the information is too extensive to provide in the response, refer to or provide links to another source of information.

• If there are several possible explanations for an error, list recovery actions, beginning with the one that is most likely to correct the error.

• Do not tell users to contact support unless there is no other option. Also, if you must ask users to contact a system administrator, describe what the administrator must do to resolve the problem.

Message variables

A message variable is a placeholder for the name of a specific file, server, database, or other object. When the message is displayed in the interface, the variable is replaced with a value. Message variables help users resolve a problem by telling them exactly what file, server, database, or other object is causing the problem.

To make it easier to translate messages that contain variables, follow these guidelines when you create message source code:

• In the source file, add comments to describe what the variables represent, or provide examples of the types of values.

• Put variables at the end of the sentence if possible.

• Use variables to replace only proper nouns. Use these proper nouns as adjectives by following the nouns with words such as file or server.

• Do not use variables to replace verbs or phrases.

• Do not use more than three variables in a sentence unless you put the variables into a list.

In addition, follow these guidelines:

• If you show messages in documentation, use meaningful variable names in an italic font. For multiword variable names, join the words with underscores.

• In source code, use double quotation marks around a variable only if the value of the variable might be long or indistinguishable from surrounding text when displayed in the user interface or in documentation.

Reason or return codes

A reason or return code is a value that is returned by a program to indicate the result of its processing. Avoid using reason or return codes to build messages and resolve problems in error handling. If you do use codes, explain them in the “Explanation” section, and describe how to respond to them in the “User response” section. If there are too many codes to include in the message, include a cross-reference or link to a separate topic that describes and explains all the codes.

Confirmation prompts

Use confirmation prompts to ask users to verify an action that the users or sometimes the system initiated. Also, use confirmation prompts to ask users for additional information to complete a step or to ask whether to save information for future use. More specifically, use confirmation prompts in cases such as the following ones:

• To confirm that users want to delete files or other data, especially if the users cannot retrieve the deleted items

• To confirm that users want to save changes to settings, properties, files, or other data

• To confirm that users want to shut down applications or the operating system

• To warn users before starting an activity that might be disruptive to the user’s progress, such as a process that takes a long time to run

• To prompt users to restart applications or the operating system so that changes to settings take effect

• To ask whether users want to store information such as passwords for future use

• To remind users of steps that the users might have forgotten

References to messages in documentation

Avoid copying the text for an individual message into a topic. For example, in a procedure, there is often no value in documenting the text of a message that is displayed in the interface. However, it might be appropriate to show message text in troubleshooting and similar topics. If you include the text for a message in a topic, follow these guidelines:

• Use the capitalization and the exact words that are shown in the interface.

• Use a plain monospace font for the message text. For variables, use an italic font.

• If you put the message on a separate line, use a blank line above and below it to further distinguish the message from surrounding text.