Interface writing

We often write technical documentation, references, collaterals, and other materials. In most of these cases it's safe to say the reader is learning something new or troubleshooting. Write clear, concise instructions that give your reader with the best possible experience.

Basics

Keep It Simple

Help the reader follow along. Break instructions or processes down into individual steps. Use short, simple sentences with words people use in everyday conversation.

Refer to navigation labels, buttons, and menus like they appear in the application or service. Verify the spelling and capitalization as you write. Your reader looks for the same name as the one in the instructions. Always boldface interface items and omit any terminal punctuation from the bold.

Be specific and give the reader as much help as you can.

Instead of:

Open a new support ticket.

Use:

Click Help > Contact Technical Support.

If the interface item is incorrectly spelled or capitalized, go with the way it is presented in the interface. The reader often looks for precisely that spelling. Contact development to suggest an interface edit.

Direct the reader

Use active verbs and clear objectives.

Instead of:

We can help you if you create a service request.

Use:

Select Support to create a help request. Include details about your problem.

Or:

To get started, select the Support link to create a new ticket. Remember to include the details of your problem.

Focus on what the reader can do rather than what they can't by using positive language.

Instead of:

You cannot submit without answering all queries.

Use:

Answer any open queries and then submit the request.

Guidelines

Interface elements

Use clear verbs to tell readers how to interact with interface elements:

Choose from drop-down menus.

Select or clear checkboxes and radio buttons.

Select, click, or tap buttons.

Follow or open links.

Bold interface names and choices:

Select File > Open. Word opens the File dialog box.
Choose the file in the list.
Select OK.

Always use the spelling, grammar, and exact names seen in the interface element.

User input

Use italic to distinguish user input from plain text. For example,

Type the exact name of the request, such as Validate Changes.

Command line items

Command line items should be in monospace. Do not use italic.

At the C: prompt, type the following: chkdsk /v /f and press Enter.