content-fundamentals

92 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

Content strategy: keep it lean

Too much content makes a tool feel cheap and hard to use. Not enough leads to confusion and frustration. Find the shortest, clearest way to give merchants only the information they need to take action. Skip punctuation except for questions or text with 2 or more sentences. Get rid of any repetition.

Writing strategy: inspire action

Focus on the one thing merchants need to know or do next. Start sentences with verbs so they feel like actionable instructions. Be direct ('add apps' not 'you can add apps'). Use design (font size, location on the screen) to communicate importance. Break multi-part tasks down into digestible steps (progressive disclosure).

Content strategy: only add necessary content

Only add content that's necessary for clarity. Let visuals and icons do the talking wherever possible, such as using '+' instead of '+ Add'. Remember that design doesn't always dictate content—not every situation calls for subcopy, even if the component has been designed to include it.

Content and design relationship

Words are an essential part of design. Very few interfaces make sense without content. However, each word and every period adds noise to the experience, so weigh every word carefully.

Writing voice: write like merchants talk

Use plain language and contractions ('don't' not 'do not'). Some jargon is okay as long as it's what actual merchants say. Aim for a 7th grade reading level—it's easiest for merchants to digest. Sound human and natural.

Disability language: 'blind' only for actual blindness

Only use the term 'blind' to reference actual blindness, not as a metaphor.

Disability language: avoid 'insane' and 'crazy'

Avoid using 'insane' or 'crazy' to describe something as extreme or unbelievable. Use alternatives such as 'wild', 'extreme', 'unbelievable', or 'intense' instead.

Disability language: avoid implying tasks are easy

When writing instructional content, avoid saying the task itself is easy or quick. If you imply it's easy for everyone, it can discourage those who might struggle. Be cautious with words like 'just', 'only', 'easy', 'simple', and 'quick'. However, when marketing, it's okay to use these words to communicate the value of a new product or feature.

Race-related language: replace 'black hat' and 'white hat'

Avoid the terms 'black hat' and 'white hat' since they imply that 'white is good' and 'black is bad'. Use 'unethical hacking' and 'ethical hacking' instead.

Race-related language: replace 'blacklist' and 'whitelist'

Avoid the terms 'blacklist', 'whitelist', and 'graylist' since they imply that 'white is good' and 'black is bad'. Use 'denylist' or 'blocklist' for blacklist, 'allowlist' or 'permit/permitted' for whitelist.

Race-related language: avoid 'grandfather in' and 'grandfather clause'

Avoid using the phrases 'grandfather in', 'grandfathered in', and 'grandfather clause' because they come from laws in the U.S. meant to circumvent or disenfranchise Black people's rights. Use 'legacy', 'legacied', or 'exempt' instead.

Race-related language: avoid 'master'

Avoid using the term 'master' because many associate it with the institution of slavery. Use 'main', 'primary', 'source', or 'expert' instead.

Gender language: use 'they/them' pronouns by default

Always use someone's preferred gender and pronouns. If you're not sure, use the pronouns 'they/them'. This keeps the content inclusive, simple, and readable. When possible, write in a way that avoids gendered language, such as using 'you' instead of a third person pronoun.

Gender language: provide inclusive pronoun options

If pronouns are necessary or useful to the experience, offer users an inclusive list of options that also allows them to opt out.

Gender language: avoid gender-associated words

Don't use language that associates roles, qualities, or objects with a specific gender. Avoid terms like 'man-made' (use 'synthetic' instead), 'manpower' (use 'workforce' instead), and 'mailman' (use 'mail carrier' instead).

Inclusive language approach: involve diverse perspectives

Start by involving different perspectives in the planning process. Limit assumptions or biases by testing your content with a diverse audience. Recruit research participants from a variety of backgrounds, including historically excluded groups. Be aware of bias, and let those with lived experiences guide the way.

Race-related language: avoid color-coded metaphors

Don't use phrases or terms that denote 'black' or 'dark' as bad or negative, versus 'white' or 'light' as good or positive. Avoid metaphors and idioms since they can have racist origins or interpretations.

Inclusive language core principles

When talking to people, use language that considers others' perspectives and lived experiences. When talking about people, be descriptive only when necessary to the context, and use language preferred by the group being described. When talking about things, be clear and accurate, avoiding metaphors and idioms.

Disability language: avoid 'disable' and 'disabled' for UI actions

Don't label actions or features using 'disable' or 'disabled' because this can imply that being disabled is a negative state. Use alternatives such as 'turn off', 'inactive', or 'deactivated' instead. However, 'disabled' is considered appropriate when talking about specific HTML element states.

Disability language: use 'Deaf' correctly

Only use the term 'Deaf' to refer to actual deafness, not as a metaphor. Use lowercase unless referring to the Deaf community.

Disability language: avoid 'handicap' and 'handicapped'

Don't use the term 'handicap' or 'handicapped' to refer to someone's disability. Be specific instead, such as using terms like 'person who requires a keyboard accessible checkout' or 'person who uses an accessibility device'.

Layout options for polaris.shopify.com documentation

Three layout configurations are available for creating documentation layouts: Full width (single column), 1-2 (one-third and two-thirds columns), and 1-1-1 (three equal one-third columns).

Top-level marketing content terminology

Top-level marketing content is created for audiences who have little context about Shopify. Use 'Shopify' here as well. Correct: 'Run your business using Shopify' or 'Print shipping labels directly through Shopify'. Incorrect: 'Use our ecommerce platform' or 'Print shipping labels directly through Shopify's admin'.

Thoughtful naming principles

Well-chosen names should put clarity above creativity, help establish a mental model for audiences, enhance perception of the Shopify brand, increase adoption of products or features, differentiate Shopify from other products, and clarify where a product or feature fits into the brand system. The naming process involves collaboration and should include different disciplines and people with different subject matter expertise.

Capitalize descriptive feature names

Do not capitalize descriptive feature names. For example, write 'order entry' not 'Order Entry'. Avoid capitalizing descriptive feature names.

When to use 'Shopify' in product names

Use 'Shopify' in front of a name when a product: is or will become a separate product or platform and needs to be associated with Shopify; should be differentiated from other similar products in the industry; or doesn't justify an evocative name but still needs to be associated with Shopify. Do not use 'Shopify' in a name for built-in functionality features like fraud analysis or importing products.

Examples of correct and incorrect 'Shopify' usage in names

Correct: Shopify Payments, Shopify App Store, Shopify Theme Store. Incorrect: Shopify Analytics, Shopify Discounts, Shopify Account.

Shopify-built apps naming convention

Shopify-built apps can use 'Built by Shopify' or 'Made by Shopify' after the app name. Examples: Shopify Product Reviews, Shopify Order Printer, Shopify Shopcodes. Once you pick the format that works for the design, use it consistently.

Third-party apps should not use 'Shopify' in name

Apps that are not built by Shopify should not use the word 'Shopify' in their name or say 'for Shopify' after the name. For example, write 'AdSpace' or 'Email Marketing', not 'AdSpace for Shopify' or 'Email Marketing for Shopify'.

Descriptive vs evocative naming approaches

Descriptive names are concrete and merchant-friendly, and are the most common approach. Features should always have descriptive names. Evocative names are more abstract and can be used for standalone products that require independent branding. Third-party apps and channels should have their own branded names and should never use the word 'Shopify' in the name.

Descriptive name best practices

Descriptive names should: describe the experiences they represent; fit into the information architecture of the product; use merchant-friendly terms, not industry standard terms; make sense in marketing materials; and align with brand. Avoid jargon and make sure the name won't get confused with similar names or terms.

Examples of correct descriptive names

Correct: Shopify Capital, fraud analysis, discounts, Logo maker. Incorrect: Shopify capital, Fraud Analysis, Shipity-do-dah. Also correct: 'Use analytics to review your store's transactions'. Incorrect: 'Use Analytics to review your store's transactions'.

Evocative name best practices

Evocative names should: have a strong, independent brand identity; help with branding or recall; reflect the concept they represent; and make sense when used in marketing materials. If you work at Shopify and want to trademark an evocative name, talk to the legal department. Unique or made-up names are easier to trademark and have stronger identities.

Examples of correct evocative names

Correct: Frenzy, Kit, Oberlo. Incorrect: Flash sales app, The Marketing Bot, Drop Shipping app. Also acceptable with more descriptive evocative names: Burst, Shop Class.

Referring to Shopify admin in documentation

Use consistent descriptions when referring to locations in product, especially in help documentation. When referring to Shopify's main product offering, use 'Shopify'. The only exception is when you need to differentiate it from another product (like the mobile app) or explain a task specific to the admin. In these cases, use 'Shopify admin'. Descriptive feature names aren't capitalized, but when providing steps in a workflow, capitalize the page name (e.g., 'Go to the Products page'). Note that the page name is capitalized but 'page' is not.

Example of correct Shopify admin terminology

Correct: 'The customer list is found on the Customers page' or 'When a new customer places an order with your store, their name and information are automatically added to your customer list.' Incorrect: 'Manage customers in Customers' or 'Customer information is automatically added to Customers in the Shopify admin.'

When to add 'app' to app names

For app names in areas with surrounding context (like the app store or Apps page in the Shopify admin), do not add the word 'app' to the end of the name. Example: write 'Oberlo' or 'Script Editor', not 'Oberlo app' or 'Script Editor app'. For app names without surrounding context (like search in the Shopify admin or on a home card), add 'app' so merchants know what it is. Example: 'Bulk Account Order app'.

Channel naming guidelines

When writing about channels, make it clear to merchants that they are interacting with a channel through Shopify, not through the other company. Correct: 'The Amazon channel now supports electronics listings'. Incorrect: 'Amazon now supports electronics listings'. If 'channel' is used somewhere in surrounding content, drop it for titles and button copy. Correct: 'Add Amazon'. Incorrect: 'Add Amazon channel'. If there is surrounding context, drop the word 'channel' from the name.

Channel type clarification

Not every channel is a sales channel. For example, BuzzFeed is a marketing outreach channel and Facebook is a sales and marketing channel. Clarify channel types when you have room; otherwise default to 'channel'. If there's room for a description, explain the channel type. Correct: 'Use BuzzFeed's marketing outreach channel to get more customers.' Incorrect: 'Use the BuzzFeed channel to get more customers.'

Capitalization rules for default features

Do not capitalize default features. Default features are built into Shopify and merchants don't have to sign up, add, or opt in to use them. Examples: analytics, discounts. Capitalize names only for independently branded evocative names, when you want to try and claim specific words, or for names listed in top-level navigation like Products.

Examples of correct capitalization

Correct capitalization: Shopify Hardware Store, Shopify Theme Store, Black Friday Cyber Monday (BFCM), Retail Package, Buy Button. Incorrect: Shopify hardware store, Shopify theme store, Black friday cyber monday (bfcm), Retail package, Buy button. Correct lowercase: analytics, fraud analysis, online store, themes. Incorrect: Shopify Analytics, Fraud Analysis, Online Store, Themes.

Acronyms and abbreviations policy

Avoid creating acronyms. Acronyms take longer to understand and might reduce adoption of a product, feature, or concept. They are like inside jokes—people who understand the acronym feel included but those who don't feel left out and confused. If you have to use an acronym, spell it out the first time you use it and follow with the acronym in brackets. Internationally understood acronyms and abbreviations are acceptable, such as 'app' or 'SEO'.

Examples of acronym usage

Avoid creating: RTE (use 'Rich text editor'), MLP (use 'Multi label printing'), MSM (use 'Merchant Success Manager'), VR (use 'Virtual reality'), BABB (use 'Build a Bigger Business'). Do not use Internet slang acronyms. Correct: 'Shop Class'. Incorrect: 'Shopify IRL'.

Internationally understood acronyms and abbreviations

Internationally understood acronyms and abbreviations are acceptable and should be used instead of spelled-out forms: SEO (not 'Search engine optimization'), NZDT (not 'New Zealand Daylight Time'), SMS (not 'Short messaging service'), QR codes (not 'Quick response codes'), HST (not 'Harmonized sales tax'), CVV (not 'Card verification value'), SKU (not 'Stock keeping unit'), ISBN (not 'International standard book number'), UPC (not 'Universal product code'), GTIN (not 'Global trade item number'), USD (not 'United States Dollar'), app (not 'Application'). Abbreviations for weight and size are also acceptable: kg (kilogram), lbs (pounds).

Currency abbreviations as adjectives

When using a country as an adjective (such as when referring to currency), use an abbreviated form without punctuation. Correct: 'Pinterest requires your store to use US currency.' Incorrect: 'Pinterest requires your store to use United States currency.'

Handling similar product and feature names

Before naming a new product or feature, conduct an audit of existing names to narrow down your naming choices, ask the support team if they think it will conflict with another name, and draft a test conversation around similar sounding names. Think merchant-first and be descriptive to differentiate the name.

Localization and translation considerations

Names may not translate directly to other languages. Before confirming a name, check with people who work in translation and localization to find out if there are cultural considerations or if a different name for a different location would have a positive impact for brand. Identify if you need to create a separate name or if a direct translation will do.

Regional language preferences for text messaging

Use 'text message' when writing for North American audiences. Use 'SMS' when writing for Indian and Nordic audiences. In India and Nordic countries, people say 'I'll SMS you', while in North America people say 'I'll send you a text.'

Name initials in logographic languages

In languages that use logographic characters, like Japanese, name initials can have different meanings. For example, in Japanese a name like Chikako (周子) Ishikawa (石川) means 'neighborhood stone' (周石) in initials. Check with the localization and translation team before writing something in short form in another language.

Avoiding negative connotations in names

Some words or terms have unintended negative connotations for some audiences. Start by getting people outside of your team to look at the name with a new perspective and doing a Google search to see if it surfaces with another meaning. Do research to avoid associating offensive words or phrases with product or feature names.

formatCurrency implementation with react-i18n

To format currency in a React component, use the `Shopify/react-i18n` library's `formatCurrency` method. Set the `form` option to either 'short' or 'explicit' to select the formatting style. Example code: ```jsx import {useI18n} from '@shopify/react-i18n'; const [i18n] = useI18n(); i18n.locale = 'de-AT'; const eurDeAt = i18n.formatCurrency(price, { currency: 'EUR', form: 'short', }); const eurDeAtExp = i18n.formatCurrency(price, { currency: 'EUR', form: 'explicit', }); ```

Store currency definition

Store currency is the main currency of the store and the Shopify default. All sales and reports are shown in the store currency.

Non-store currency types

Non-store currency types include: presentment currency (the type of currency presented to buyers in a merchant's store, can differ from store currency in multi-currency stores), payout currency (the type of currency used to pay merchants for their sales, can differ from store currency in multi-currency stores), and billing currency (the type of currency used to bill merchants for themes, app purchases, and monthly subscriptions; billing currency is in USD only but might include local currencies for tax purposes).

Short format definition

Short format includes the currency symbol and currency value. This format is used for currency that merchants are familiar with. Examples: $12.50; 12,50 €

Explicit format definition

Explicit format includes the currency symbol, currency value, and ISO code (for example, USD or CAD). It is best used for currency that merchants aren't familiar with and don't expect to see. Examples: $12.50 CAD; 12,50 € EUR

CLDR international standard for currency formatting

Shopify uses Common Locale Database Repository (CLDR) for localization formatting of currency, date, time, and amount. CLDR is the recognized international standard maintained by a third party. It automatically formats numbers and currency based on the merchant's locale.

What CLDR determines in currency formatting

CLDR determines whether the currency symbol appears before or after the amount (for example, $250, 250 USD, 250 $), whether decimals are used (for example, Japanese yen has no cents), whether the decimal sign is a period or a comma (37,50 or 37.50), and how to group numbers (10,000 or 1,0000 or using spaces).

CLDR limitation in currency formatting

CLDR does not determine the appropriate level of detail shown in different contexts. For example, it cannot determine when to show the currency symbol and value (short format) or the currency symbol, value, and ISO code (explicit format).

Store currency formatting for merchants

Default to short format for store currency. Use explicit format only when presenting store currency within a mixed-currency context.

Non-store currency formatting for merchants

Use explicit format when showing total amounts, an amount within a button, or in a paragraph. Use short format when showing non-total amounts with total amounts.

Give your agent this brain