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

KISS Keep It Simple Stupid

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 the same way they appear in the application or service. Verify the spelling and capitalization as you write. Your reader looks 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.

If the interface item is incorrectly spelled or capitalized, go with the way it is presented in the interface. The reader often looks for exactly that spelling. Put in a ticket to get the interface changed.

Direct the reader

Use active verbs and clear objectives.

Instead of:

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

Use:

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

Or:

To get started, select the JIRA Service Desk 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 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:

• Nouns -- Proofs, Users, Task
• Verbs -- Create an account, Print a report, Submit a proof

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. This will also 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.

Select, click, or tap buttons.

Follow or open links.

Bold interface names and choices:

1. Select File > Open. Word opens the File dialog box.
2. Choose the file in the list.
3. 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 Proof.

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.