Interface writing

We often write technical documentation where it's safe to say the reader is learning something new or troubleshooting. Write clear, concise instructions to provide the best possible experience to the user.

Basics

Do the hard work to make it simple for the user

Help the user follow along. Break instructions and processes down into individual steps. Use short, simple sentences with words the user will recognize and understand.

Refer to navigation labels, buttons, and menus as they appear in the app. Verify the spelling and capitalization as you write. Users look for the same name as in the instruction. 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.

Direct the reader

Use active verbs and clear objectives.

Instead of:

We can help you if you create a JIRA Service Desk request.

Use:

Click JIRA Service Desk to create a help request. Include details about your problem.

Or:

To get started, click the JIRA Service Desk link to create a new ticket. Remember to include the details of your problem.

Us positive language and focus on what the reader can do rather than what they can't do.

Instead of:

You cannot submit without answering all queries.

Use:

Answer any open queries and then submit the proof.

Guidelines

Titles and headings

Use consistent naming by sticking to the same naming convention. This makes it easier for the reader to scan and find what she's looking for. For examples:

Use sentence case for headings.

Introduction

Include a short two- or three-sentence summary about the document to help the reader confirm whether they're in the right place, and also to improve searchability.

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.

Click or tap buttons.

Follow or open links.

Bold interface names and choices:

  1. Click File > Open. Word displays the File dialog box.
  2. Select a file.
  3. Click OK.

Always use the spelling, grammar, and exact names seen in the interface element, even if they are grammatically incorect.

User input

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

Type the exact name of the dialog box, such as Exit system.

Command line items

Command line items should be in monospace, such as Courier, Consolas, or similar. Do not use italic for this form of user input.

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