Content

Writing and designing content in a thoughtful way makes your app usable, accessible, and readable.

Voice and tone

Anchor link to section titled "Voice and tone"

Your written content’s voice and tone help you talk to merchants in a consistent, recognizable way.

Voice refers to aspects of writing that are consistent across all contexts and audiences. Tone can change based on the audience and their current context.

Learn how to apply Shopify’s voice and choose the right tone, no matter what app you’re building, by referring to the Polaris guidelines on voice and tone.

A mockup of the Puzzlify app with highlighted bits of text.

Product content

Anchor link to section titled "Product content"

The following are some principles behind writing product content for a quality merchant experience.

Various cards of the Puzzlify app showing different types of content.
A single UI page that provides two different ways to accomplish the same task.

Do Not

Don’t duplicate content, such as adding a page title under the App Bridge-set page title, adding horizontal navigation when using the App Bridge ui-nav-menu web component or NavMenu React component, or presenting the same content in different ways on the same page.

Use plain language

Anchor link to section titled "Use plain language"

Shopify merchants are located all over the world, have varying levels of literacy, and might not speak English as their first language. Content can easily be mistranslated or misinterpreted.

Structure your content in a clear, efficient way.

A card with a clearly visible heading and bulleted list.

Must Do

Use headings, bullets, and short sentences to make your content more scannable.
A card with text that’s written at a seventh-grade level.

Must Do

Use clear terms that are easily understood. As a benchmark, aim for a United States grade 7 reading level. You can check reading levels with tools like Hemingway App.
A card that gives the definition of ‘Interjamb’, which is puzzle industry jargon.

Do Not

Don't use jargon or overly technical language that might be difficult for merchants to understand.
A card with a very long paragraph of text.

Do Not

Don't use large blocks of text, because they're hard for merchants to scan and gather the most important information quickly.
A card with a title that reads ’Beggars can’t be choosers’.

Do Not

Don't use idioms and phrases with indirect or ironic meanings, as they can be misinterpreted or mistranslated.

Be consistent

Anchor link to section titled "Be consistent"

To help merchants understand key concepts and actions, use terms in a consistent way.

One way to ensure consistency is to identify and eliminate synonyms for key concepts and actions.

A card's text and button consistently using the same words, "Upload image", to indicate a single action.

Must Do

Use a single noun, verb, or phrase to describe a specific thing, action, or concept.
A card's text and button using different words, "Upload images" and "Add photos", to indicate a single action.

Do Not

Don’t use multiple synonyms to describe a specific thing, action, or concept.

Encourage action

Anchor link to section titled "Encourage action"

Merchants use Shopify to get things done for their businesses. Write content that helps merchants understand and take the most important actions.

Two buttons with strong calls to action, "Export templates" and "Create template".

Must Do

For calls to action (CTAs), start with a strong verb that describes the action. Use active voice to clarify the subject and the action.
A numbered list of three tasks to complete.

Must Do

Prioritize the most important information and tasks. Break complicated tasks into steps that focus on individual actions.

Guide, don’t prescribe

Write in a way that puts your merchant at the center and in control. Provide merchants with tools and knowledge for making the best decision.

A card that clearly and concisely explains how autopayment works and provides a button for setting it up.

Must Do

Give merchants enough information to make the right decision on their own.

Grammar and mechanics

Anchor link to section titled "Grammar and mechanics"

For spelling, punctuation, and other grammatical considerations, refer to the Polaris guidelines on grammar and mechanics.

Screenshots of the Polaris grammar and mechanics page, which explain guidelines for using special characters, dates, numbers, and measurements.
A message where Puzzlify refers to itself multiple times. The message says "Puzzlify detected an issue with your shipment". It then says "We’ve contacted our supplier and will send you updates as we receive them."

Must Do

In the first reference to your app or company, use its proper name to avoid confusing merchants. If you require additional references in the same content section, then you can use "we". This helps maintain clarity while keeping the content concise.