Writing about the interface

Content at Intuit

Customers come to our products to get things done, not to read about menus and buttons. And language about links, navigation, and such might not always be accessible. But sometimes, especially in help content or conversation design, we need to talk about the interface to keep things clear. Here’s how to do it in ways that are conversational and simple.

Capitalization

When you’re referring to a term in the UI, match the capitalization of the term as it appears there. If you’re making a general reference, there’s no need to capitalize.

For example, you’d say Select Chart of Accounts as a direct, instructional reference. And you’d say Your chart of accounts has all of your transactions as a general reference to it. Since the chart of accounts is not a proper noun or a branded term, there’s no need to capitalize it in this situation.

Examples

  • Select Settings ⚙
    Your settings contain everything you need to…
  • Select Account and Settings
    Run payroll

Always capitalize branded terms to match their official style. This is usually for product names. Look at Intuit’s website for the most updated info on products.

Never use shouty caps (LIKE THIS) for emphasis. It’s rude. Use a visual callout box if truly necessary.

Sometimes a UI element or a message in the UI is long and has mixed capitalization. If you need to be so specific as to use the entire message, put it in quotes so it’s clear what part your sentence is from the UI versus other parts of the sentence.

Examples

  • If you see the message “QuickBooks has encountered Error 6001: Your bank connection is not available,” here’s what to do.

When to use bold

In help, use bold only for things the user selects. Don’t bold things like areas or column headers that organize info that the user doesn’t actually click or select.

Don’t use bold just for emphasis. Bold copy can make a screen look cluttered, intimidating and difficult to scan. And terms in bold can draw too much attention to content that doesn’t need to be the customer’s focus. Sometimes UI instructions appear on a screen, but they’re not the primary purpose of that screen. In those cases, bolding UI elements can be a distraction that keeps the customer from moving forward.

Additionally, don’t use italics or quotations to distinguish UI elements. Quotations are OK when you need to distinguish a long verbatim from the UI with mixed capitalization.

Examples

  • From the Edit menu, select Delete.
  • In the Actions column, select More next to the user ID.
  • Note: It’s OK not to bold the word note.

Actions



  • Choose the best partners for your business.

Use choose when referring to a customer decision that isn’t UI-related.

Use select for anything a user clicks or taps after.

Use tap only if your only use case is mobile.

  • Deselect the checkbox for any items you don’t want.

Don’t use deselect. Instead, use clear. Deselect sounds like technical jargon and is difficult to translate.

  • Go to Banking and select the Receipts tab.

Use go to or from for top-level navigation.

Use select for anything a user clicks or taps after. Use tap only if your only use case is native mobile.

Directing someone through the UI

There are many ways to direct customers to files, folders, websites, or pages. The important thing is to be as clear as possible so customers can find their way easily.



  • Find the customer you want to send the invoice to.

Find is a good alternative to search when you want the customer to feel empowered. For example, it’s more effective in the UI to use the phrase Find customers instead of Search customers because the word “find” implies success. Find is also a good option for simplicity and maintains a friendly tone.

  • Go to Banking > Receipts

Don’t use the angle brackets > to separate UI elements. Nobody talks that way. Instead, write out the path with the word select.

  • Browse to the folder where you stored the backup file.
  • Locate the mylogo.gif file.

Browse or locate are good choices when directing customers to files, folders, or drives on their desktop. Browse is the common button name in the Windows interface that customers select to see their files list, so telling them to browse helps associate the action with the button. Browse is often used for folder locations. Locate works well when the customer has actively saved or stored a file themselves and you don’t need to be specific about the location of the folder.

  • Go to the Banking tab above the arrow on the left side of your screen.

For accessibility reasons, we strongly discourage using location cues or directions like above or below.

  • Go to maps.google.com/maps?f=q&source for a map to the conference.
  • Go to Banking and select the Receipts tab.

Go to gives the sense that the customer is moving away from where they are and going to another location. Use “go to” when you need to direct the customer away from their current workflow or location in the product. For example, when you need them to go to a specific page.

Specific UI elements

Here’s how we write about some specific UI elements. It’s OK to refer to an element by name without specifically calling out what it is (icon, button, tab, etc.). But you can be more specific if you think it will add clarity, especially if there are many items on a page.

Examples

  • Select Receipts (preferred)
  • Select the Receipts tab (OK)

Icons

For accessibility reasons, you should check the Aria label for any icon you’re mentioning.

In help, refer to the icon by the label name and with a representative emoji so all users have a way to recognize it.

In conversation design and push notifications, it’s OK just to use an emoji for the icon. For icons that have a close but not perfect emoji equivalent, use a descriptive word and emoji together. Don’t capitalize or bold the descriptive word. Use the word icon after the emoji.

Here’s a quick reference list for how screen readers read these common icons in QuickBooks Online:

  • ⚙ is settings
  • ≡ is navigation
  • ⨁ is create
  •  ✎ is edit
Help

Examples

  • Go to Settings ⚙ and select Account.
    Select Edit ✎ next to the user ID.
    Go to the Create ⨁ icon and select Estimate.
Conversational bot and notification

Examples

  • Go to ⚙ and select Account.
    Tap the pencil ✎ icon.

Arrows

Arrows are no longer labeled. For clarity, you can add back and forward. Even better, we can rewrite these examples to avoid talking about the arrows directly.

Examples

  • Go back (preferred)
  • Go to the next transaction (preferred)
  • Select the arrow to go back (OK)
  • Select the forward arrow to move to the next transaction (OK)

Dropdown menus

Be specific about how to identify the dropdown menu (don’t just say “from the dropdown menu”). Use the small arrow emoji ▼ with the name of the menu if it’s present.

Examples

  • From the Edit ▼ dropdown menu, select Delete.
  • Select the small arrow ▼ icon next to the username.

Left navigation or menus

You can use menu to make it clear that we’re talking about the options in the left navigation or menu bar. Or you can just say Go to Banking, for example.

Use go to when navigating the customer to a menu, especially if it fits with the tone of the wizard, experience, message, web page, or email.

Examples

  • Go to Taxes, then Payroll tax.
  • Go to the Expenses menu and select Vendors.
    (If a customer is already on the Expenses page, then: Select the Vendors tab)

Container or area (screen, page, window, section)

We usually prefer screen to page, but try to avoid using either word. It’s OK to say area.

We can use the word page when referring to an interview, wizard, website pages, or a homepage. Use (page name) page to refer to web pages that come up in embedded browser windows.

When referring to a page, use your judgment about its title. Use the text that is the most visible and recognizable to the customer and unique to the page. You can mention the title bar name or the header on the screen.

When you need to write about a card or container (usually a box) that appears on top of the UI and presents info to the user or requests a response, call this a window. But, again, try to avoid referring to the card or container at all, and instead focus on its content.

Tabs

Set the name of the tab in sentence case. For example, if you’re already on the Expenses page, you can write Select the Vendors tab.

Link copied