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.
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.
Always capitalize branded terms to match their official style. This is usually for product names. See the QuickBooks Design System for more detail on product names.
Never capitalize something (LIKE THIS) for emphasis; it’s a bit rude. Use a visual callout box if truly necessary.
- Select Settings ⚙
Your settings contain everything you need to…
- Select Account and Settings
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 that it’s clear what part your sentence is from the UI versus other parts of the sentence. Example: 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. Italics are difficult to read in digital experiences. However, quotations are OK when you need to distinguish a long verbatim from the UI with mixed capitalization.
- 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, go to, select, tap, click, etc.)
- Use “choose” when referring to a customer decision that isn’t UI-related.
- 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 mobile.
- Don’t use “deselect.” Instead, use “clear.” “Deselect” sounds like technical jargon and is difficult to translate.
- Choose the best partners for your business.
- Go to Banking and select the Receipts tab.
- Clear the checkbox for any items you don’t want.
Directing the user 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 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.
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 click 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” 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.
Don’t use the angle brackets > to separate UI elements. Nobody talks that way. Instead, write out the path with the word “select.”
For accessibility reasons, we strongly discourage using location cues or directions like “above” or “below.”
- Find the customer you want to send the invoice to.
- Browse to the folder where you stored the backup file.
- Locate the mylogo.gif file.
- Go to maps.google.com/maps?f=q&source for a map to the conference.
- Go to Banking and select the Receipts tab.
Specific UI elements (icons, buttons, menus, etc.)
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.
- Preferred: Select Receipts
- OK: Select the Receipts tab
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”
- or ✎ is “edit”
- Go to Settings ⚙ and select Account.
Select Edit ✎ next to the user ID.
Go to the Create ⨁ icon and select Estimate.
- See more info on this page about the difference between Create ⨁ icon and (+) button.
Conversational bot and notification
- Go to ⚙ and select Account.
Tap the pencil ✏️ icon.
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.
Select the arrow to go back.
Select the forward arrow to move to the next transaction.
Go to the next transaction.
Be specific about how to identify the drop-down menu (don’t just say “from the drop-down menu”). Use the small arrow emoji ▼ with the name of the menu if it’s present.
- From the Edit ▼ drop-down 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, first-time-use experience, message, web page, or email.
- 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.
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.”
The (+) button and the Create ⨁ icon
The (+) button appears in the QuickBooks Self-Employed App. The Create ⨁ icon appears in QuickBooks Online. Refer to them accordingly.