#### Donât
-Your store must be located in the US.
+
+
+
+
-When using a country as an adjective (such as when referring to currency), use the abbreviated form without punctuation.
+#### Referring to Shopify
+
+Always refer to Shopify as âwe,â but avoid inserting Shopify into the content as much as possible (except when a human is taking action, such as reviewing a request).
#### Do
-Pinterest requires your store to use US currency.
+Pinterest Buyable Pins will be available in the coming weeks.
#### Donât
-U.S. currency
+Weâre making Pinterest Buyable Pins available in the coming weeks.
-Things to watch out for:
-
-- Donât use colloquial forms of a nation or state name, for example, America instead of the United States
-- Search online to see whether nations commonly use âtheâ before their name, for example, the Philippines or the Falkland Islands
-
---
## Punctuation
-### Ampersands
+#### Ampersands
Donât use ampersands (&). They attract attention to the least important part of the sentence. Spell out the word âand.â
@@ -839,7 +851,7 @@ Zones & rates
-### Apostrophes
+#### Apostrophes
Use apostrophes to represent omitted letters or numbers:
@@ -904,7 +916,7 @@ Always use apostrophes, not vertical (straight) quotes.
-### Colons
+#### Colons
Avoid using colons in sentences. If you need to use one, donât capitalize the first word after the colon unless itâs a proper noun.
@@ -956,7 +968,7 @@ Correct the following payment information to continue.
-### Commas
+#### Commas
Use the oxford comma (also known as the serial comma) in sentences. There should be a comma after every list of 3 or more items (unless youâre using a bulleted or numbered list).
@@ -990,7 +1002,7 @@ Donât use commas to separate bulleted or numbered list items.
-### Ellipses
+#### Ellipses
The ellipses (âŠ) can be used in place of a missing piece of text (most commonly to show the deletion of words from a direct quotation). Avoid using ellipses in text.
@@ -1052,7 +1064,7 @@ Consider constraints of the space in the interface when deciding to use truncati
A button with an ellipsis icon (not the same as text) is used to expand more actions. Itâs typically used in cards, or for horizontal sets of actions when space is limited.
-### En-dashes and em-dashes
+#### En-dashes and em-dashes
Use an en dash with no spaces in between (â) for a fixed range of numbers
@@ -1086,7 +1098,7 @@ Depending on the font or appearance, you may want to include a hair space on eit
Tip: On Mac the keyboard shortcuts are option - for en dash and shift option - for em dash.
-### Exclamation marks
+#### Exclamation marks
Avoid exclamation marksâonly use them for really really exciting things. If you absolutely have to, limit yourself to one exclamation mark per page.
@@ -1102,7 +1114,7 @@ Youâve updated your product title!
-### Hyphens
+#### Hyphens
Use hyphens to:
@@ -1144,51 +1156,21 @@ Use hyphens to:
-### Periods
-
-Periods often end up in places they shouldnât, and are omitted at strange times. In general, donât use periods in interface copy unless itâs a full sentence description.
+#### Periods
-When to use periods:
+- Don't use periods in interface copy
+- If text includes 2 or more sentences, it's okay to use periods
-
-
-#### Do
-
-- Complete sentences
-- Body text, descriptions, and subtitles
-- Help text under text boxes (form fields)
-- Timeline events
-
-#### Donât
-
-- Sentence fragments
-- Top-level headings and titles
-- Buttons
-- Notifications
-- Toast messages
-- Placeholder copy
-- Navigation menu items
-- Hover/tooltip text
-- Footer help box text
-- Radio button and checkbox text
-
-
#### Do
-- Description example: Add this product to a collection so itâs easy to find in your store.
-- Placeholder example: Search products
-- Timeline example: \$50.41 USD was authorized.
-- Footer help box example: Learn more about [products](https://help.shopify.com/manual/products)
+Add products to collections so they're easy to find
#### Donât
-- Button example: Add product.
-- Placeholder example: SearchâŠ
-- Heading example: Iâm Kit, your virtual employee.
-- Notification example: 6 orders have payments that need to be captured.
+Add products to collections so they're easy to find.
@@ -1208,7 +1190,7 @@ When to use periods:
-### Question marks
+#### Question marks
Avoid question marks wherever possible. Reword into affirmative statements wherever you can, but there are exceptions:
@@ -1234,7 +1216,7 @@ Donât use question marks if:
-### Quotation marks
+#### Quotation marks
Use quotation marks to:
@@ -1351,7 +1333,7 @@ Always use smart (curly) quotes, not vertical (straight) quotes.
-### Semicolons
+#### Semicolons
Avoid semicolons if possible. If you really need them, use semicolons to:
@@ -1372,9 +1354,9 @@ The unicorn was hungry; the grass was brown.
---
-## Spelling and formatting
+## Spelling
-### American spelling
+#### American spelling
Use American spelling for all external-facing Shopify content. When in doubt, check the [Merriam-Webster dictionary](https://www.merriam-webster.com/) for the preferred spelling of specific terms.
@@ -1396,81 +1378,5 @@ Use American spelling for all external-facing Shopify content. When in doubt, ch
Tip: itâs easy to miss Canadian spelling. Switch your laptop language settings to American English and turn spell check on. It will highlight any Canadianisms you might have missed.
-### Bold
-
-When in doubt, donât bold.
-
-Use bold sparingly and only where strong emphasis is required. Donât use bold to create a heading or emphasize:
-
-- Proper nouns
-- Merchant input
-- Checkbox titles
-
-
-
-#### Do
-
-After your first sale, PayPal will email you at **merchant@email.com** with instructions.
-
-#### Donât
-
-Are you sure you want to delete **Sunset T-shirt**?
-
-
-
---
-## You, we, and other personal pronouns
-
-### Addressing merchants
-
-Always refer to merchants as âyou.â Donât speak for merchants with phrases that use âIâ or âmy.â
-
-
-
-#### Do
-
-Change your email address in your Profile.
-
-#### Donât
-
-Change your email address in My Profile.
-
-
-
-In some cases (such as getting merchant consent or granting permissions) you should refer to merchants as âI.â
-
-
-
-#### Do
-
-
-
-
-
-#### Donât
-
-
-
-
-
-
-
-
-### Referring to Shopify
-
-Always refer to Shopify as âwe,â but avoid inserting Shopify into the content as much as possible (except when a human is taking action, such as reviewing a request).
-
-
-
-#### Do
-
-Pinterest Buyable Pins will be available in the coming weeks.
-
-#### Donât
-
-Weâre making Pinterest Buyable Pins available in the coming weeks.
-
-
diff --git a/polaris.shopify.com/content/content/help-content.mdx b/polaris.shopify.com/content/content/help-content.mdx
deleted file mode 100644
index baee28039fd..00000000000
--- a/polaris.shopify.com/content/content/help-content.mdx
+++ /dev/null
@@ -1,101 +0,0 @@
----
-title: Help content
-description: Help content is educational text that describes interactive elements or offers information about concepts in the UI.
-icon: QuestionCircleIcon
-keywords:
- - help text
- - learn more
- - help center
- - help
----
-
-# {frontmatter.title}
-
-{frontmatter.description}
-
-The goal of help content is to teach merchants:
-
-- How to complete a task or make a good decision for their business
-- Important information related to the current workflow
-- How to optimize the way they use Shopify
-
----
-
-## When to use less, when to use more
-
-â
-The choice of whether or not to use help content depends on the kind of experience youâre designing.
-
-### Productivity areas
-
-â
-Productivity areas include tasks that merchants do regularly, like adding products and fulfilling orders. These pages are used often and become familiar quickly.
-
-When designing productivity experiences, prioritize experienced merchants. This is their space to get work done and we can keep out of their way by offering a clean, streamlined UI. This means minimal help content.
-â
-
-### Educational areas
-
-â
-Educational areas include tasks that merchants do infrequently, like adjusting tax or payments settings. Most of these settings arenât changed very often, so merchants doing these tasks are often seeing them for the first time.
-
-When designing for educational experiences, prioritize merchants who are unfamiliar with the task or workflow. Offer context and guidance to help them make the right decisions for their business. This means making use of help content.
-
----
-
-## Place help where itâs needed
-
-â
-Help content belongs as close as possible to the part of the UI it references. If itâs teaching merchants about the purpose of a card, put it at the top of the card as a description. If itâs teaching merchants about a particular field, put it beneath the field as help text.
-
-The following is an example of help content that was originally a card description, but felt easier to parse after moving closer to the upload actions it helps with.
-
-#### Before
-
-
-
-#### After
-
-
-
----
-
-## Avoid a marketing tone
-
-â
-Using help content to promote new features can erode trust with merchants. Not every feature is the best choice for every merchant at every point in time, and we shouldnât assume that they want or need it.
-
-There are times when our motivations and our merchantsâ are highly aligned, and encouraging a certain action through help content might be appropriate. An example of this is discounted annual billing. Itâs good for Shopify because of the long-term merchant commitment and up-front payment. Itâs good for merchants who are long-term committed to Shopify and can pay up front.
-
-This example also illustrates that thereâs still only a subset of merchants that are at the right place to adopt it. Keep this in mind when suggesting how a feature might help someoneâs business.
-
----
-
-## âLearn moreâ links
-
-â
-âLearn moreâ links take merchants to the Shopify Help Center or Shopify.dev for more detailed information than we can offer in the UI.
-
-Make sure âLearn moreâ links go to a page or heading thatâs specific to the topic.
-
-The Help Center is a rich resource, but for a merchant itâs not always a convenient time to read documentation. Landing on a dense page of information without knowing where to start is frustrating and disorienting. If there isnât a page or heading specific to the topic youâre providing help for, work with the documentation team to create the right content.
-
-See the content guidelines for links for more about [formatting âLearn moreâ links](/content/actionable-language#-learn-more--links).
-
-### âLearn moreâ badges for settings
-
-â
-âLearn moreâ badges show an information icon that takes you to the Help Center. These are different from tooltips. On large screens, they expand on hover to reveal a âLearn moreâ link.
-
-
-
-Use âLearn moreâ badges:
-â
-
-- Only in settings experiences, and only in card headers
-- When the linked Help Center topic is relevant to the entire card
-
-Best practices:
-
-- Use regular âLearn moreâ links for help topics specific to only a part of a card
-- Some cards benefit from a âLearn moreâ badge in the heading in combination with âLearn moreâ links or other help content in the card body
diff --git a/polaris.shopify.com/content/content/help-documentation.mdx b/polaris.shopify.com/content/content/help-documentation.mdx
deleted file mode 100644
index b35fc43e0e2..00000000000
--- a/polaris.shopify.com/content/content/help-documentation.mdx
+++ /dev/null
@@ -1,644 +0,0 @@
----
-title: Help documentation
-description: After you build an app or other integration, writing help documentation will show merchants how to use it.
-icon: QuestionCircleIcon
-keywords:
- - writing instructions
- - writing guides
- - writing tutorials
- - writing how-to's
- - writing how to's
- - writing how to
- - writing step-by-steps
- - writing step by steps
- - writing technical documentation
- - technical documentation
- - linking to help documentation
- - linking to technical documentation
- - educating
- - teaching
- - explain apps
- - describe apps
- - educate about apps
- - merchant education
- - educational opportunity
- - educational opportunities
- - explain features
- - describe feature
- - educate about features
- - merchant education
- - educational opportunity
- - educational opportunities
----
-
-# {frontmatter.title}
-
-{frontmatter.description}
-
-These are the core guidelines used to produce the [Shopify Help Center](https://help.shopify.com/), as well as Shopify's internal documentation. Theyâre all intended to serve the same goal: to educate and empower Shopify's merchants and employees.
-
-To include a link to help documentation in your app or channel, use the
-[Footer help](/components/navigation/footer-help) component.
-
----
-
-## Plan for your audience
-
-The way that you write your help documentation should change depending on your intended audience and their expectations. Take some time to understand your audience and determine the documentation that would suit them best. For example, if your audience is mainly in the United States, then you should use American English. For a more worldwide audience, British English is more common and expected.
-
-Reviewing your intended audience and understanding the language that they expect can improve the effectivenss of your help content, improve adoption of your product and features, and reduce support debt costs.
-
-### Audience types
-
-Using Shopify as an example, there can be a wide spectrum of Shopify users as an audience. Often, individual pages are written with a certain audience in mind, as opposed to the whole help center being written with one central audience being considered.
-
-#### Prospective users
-
-- Not signed up yet, possibly on a free trial
-- Could be new to business, or could be looking to migrate an existing business
-
-#### Novice users
-
-- Signed up but might not have sold online before
-- Possibly not very computer literate
-- New to Shopify concepts and workflows
-
-#### Experienced, confident users
-
-- Have been using Shopify for some time
-- Familiar with the basic concepts and workflows
-- Confident with computers
-- Can try some customizations with guidance
-
-#### Highly technical users
-
-- Experienced and confident
-- Extensive computing experience
-- Happy to experiment and take risks
-- Experienced problem solvers
-- Self-serve through forums and help documentation
-
-### Audience expectations
-
-Each of these different users likely has different expectations for the same document. Letâs take a look at how that might play out:
-
-#### Prospective users
-
-- A quick-start guide
-- Conceptual overviews
-
-#### Novice users
-
-- Detailed explanations
-- Clear step-by-step instructions
-- Conceptual overviews
-- Definitions of terms
-- Tutorials
-- Context-sensitive help
-
-#### Experienced, confident users
-
-- Clear step-by-step instructions
-- Conceptual overviews
-- Definitions of terms
-- More challenging tutorials
-- Context-sensitive help
-
-#### Highly technical users
-
-- Procedural instructions (can be brief and direct)
-- Code fragments
-- Links to information sources
-
-This is just one way to imagine the variety of users that fit into Shopify's audience.
-
-Regardless of their skill level, the aim of the documentation remains the same: to accommodate a wide range of users and their objectives. This can be achieved by presenting information in a way thatâs inclusive of different skill levels, learning styles, and workflows.
-
----
-
-## Core help content principles
-
-Before you begin organizing information on a page, review the following principles:
-
-- **Let readers fail fast**: If a reader is going to fail at the task at hand, then let them know quickly, instead of letting them get halfway through only for them to realize that they don't meet the requirements. If a reader can't complete a set of steps due to an unmet requirement, isn't eligible to use a feature, or is in a scenario where continuing to pursue an action is a waste of time, then you need to inform the reader of this fact as quickly as possible within the content. This respects a reader's time, and lets them find an appropriate solution faster.
-
-- **Provide all readers with a solution or next step**: Any given set of steps should include a solution or next step for a reader. For example, suppose that a set of steps has the successful result of adding a feature to their product, but there is a requirement to be on the latest version of the product. Before the steps are listed, a user should be told of the restriction, and provided a link for the steps on how to upgrade.
-
-- **Keep it factual**: To maintain a level of trust with your readers, you should remove marketing and promotional content from your help content. Help content can be used to explain the benefits of a product or feature, but should stick to the direct benefits and hedge all claims of making things "faster", "better" or "easier".
-
-- **Explain how a reader can use a feature, not what a feature can do for them**: Framing your content as how a reader can use a product or feature helps them better understand your content and imagine how it would fit into their own context.
-
-## Use headings to organize your document
-
-Readers come to help documentation with different expectations and in different usage settings:
-
-- One might be working through a long, multi-stage setup process to connect a third-party app into their admin
-- Another might be using her tablet to check out the details of Shopify POS and see if it could be used at their cafe
-- Another might be trying to make a quick edit to his storefront in the half hour they have left before going to pick up their kids from school
-
-In all these different cases, the reader needs documentation thatâs findable, usable, and relevant. In other words, content that is organized.
-
-Headings help readers pinpoint the most relevant content on a page for them, and reduce the need to scan and browse content.
-
-### Effective headings
-
-Effective headings make it clear to readers which sections of a document are most relevant to their current tasks. The heading should directly reflect the result of any actions, or should summarize the content found within the section.
-
-Headings also provide readers with a good sense of progress while they move from one task to the next.
-
-### Low-level headings
-
-As a general rule, the lower a heading is in the docâs hierarchy, the more flexible you can be with its tone. For example, low-level headings can be longer and more specific, or less formal.
-
-### Heading hierarchy
-
-Maintain the heading hierarchy throughout the doc, and donât skip heading levels. For example, go directly from H1 to H2, then to H3, and so on. This helps the readers know where they are in the document, whether theyâre going through a specific workflow or just scanning.
-
-### Tips
-
-For page or topic-level headings, use short, gerund-based (verb ending in "ing") statements.
-
-
-
-#### Do
-
-- Creating products
-
-#### Donât
-
-- Create products
-
-
-
-For task-based headings within the document, use imperatives.
-
-
-
-#### Do
-
-- Add a customer
-
-#### Donât
-
-- Adding a customer
-
-
-
-Avoid pronouns in headings.
-
-
-
-#### Do
-
-- Connecting Facebook accounts
-- Connect a Facebook account
-
-#### Donât
-
-- Connecting your Facebook account
-
-
-
-Avoid long strings of nouns in a heading.
-
-
-
-#### Do
-
-- Posting products
-- Creating posts
-
-#### Donât
-
-- Creating Point of Sale product collections
-- Creating product post pages
-
-
-
-Keep the key descriptors close to the front of a heading so itâs easier to scan quickly. For example, avoid starting the heading with âHow toâ or âTo.â
-
-
-
-#### Do
-
-- Add a product
-
-#### Donât
-
-- How to add a product
-
-
-
-Try to keep parallel grammatical structure between headings of the same level.
-
-
-
-#### Do
-
-- Boost a post, Choose an audience, Fulfill an order
-
-#### Donât
-
-- Boost a post, Choosing your audience, How to fulfill your orders
-
-
-
-In most cases, headings should be statements rather than questions. Save question-style headings for FAQs or low-level headings that address specific functions.
-
-
-
-#### Do
-
-- Add a product
-
-#### Donât
-
-- How do I add a product?
-
-
-
-Use sentence case for all headings, but no periods at the end. Format and capitalize interface elements or buttons in the way they appear in the Shopify admin.
-
-
-
-#### Do
-
-- Adding products to your store
-
-#### Donât
-
-- Adding Products To Your Store.
-
-
-
-Use parallel structure in your content, such as in lists and headings, to encourage comprehension and recall.
-
-
-
-#### Do
-
-- Adding products to your store, Deleting products from your store, Editing products in your store
-
-#### Donât
-
-- Add products to your store, How to delete products from your store, Edit a product in your store
-
-
-
----
-
-## Document tasks
-
-### Be task-oriented
-
-Most help documentation is task-oriented: itâs designed to guide readers through the steps they need to follow to complete a task. The best documentation will save readers time by helping them complete their tasks quickly. The way that you present information has a big impact on how useful it will be to your readers.
-
-### Use introductions
-
-In most cases, a document shouldnât start with a set of instructions. Instead, offer context with an introductory comment or define a key concept about the topic. Decide what information readers need before they scan the instructions.
-This is also true for the documentâs subsections.
-
-### Use numbered steps
-
-Divide up the instructions in a way that reflects how the reader might think of the task. Use numbered steps for each part of the task. This helps to hold your readerâs attention, and makes it easier for them to switch between a help document and Shopify to complete the task.
-
-### Start at the beginning of a workflow
-
-Make sure that the instructions for major tasks in a longer document can stand alone. If the instructions for a task pick up abruptly where an earlier task left off, then the readers who begin at that point might struggle to figure out the workflow. Start documenting each task at the beginning of the workflow required to complete it.
-
-### Use short lists
-
-In general, use short lists (either numbered steps or bullets), which are easier to read than long lists. If you have a task or a list that needs more than ten items, then break it up into two or more lists, each with their own subheading.
-
-### Make tasks actionable
-
-Tell the user what they can do with your product, not what it can do. This means structuring documentation around user actions rather than product features.
-
-
-
-#### Do
-
-- Use this feature to keep track of key updates and promotions.
-
-#### Donât
-
-- This feature notifies you about key updates and promotions.
-
-
-
-In general, avoid grouping multiple actions together in a single numbered step.
-Each step should include only one or two user actions.
-
-
-
-#### Do
-
-1. From your Shopify admin, click **Products**.
-2. Click **Add a product**.
-
-#### Donât
-
-1. From your Shopify admin, click **Products**, click **Add a product**, and
- then enter your product information.
-
-
-
-Avoid telling the user to âfindâ or âlocateâ something in a task.
-
-
-
-#### Do
-
-- In the Pinterest section, click **Remove channel**.
-
-#### Donât
-
-- Find the Pinterest section, then click **Remove channel**.
-
-
-
-Use the action word âselectâ when youâre telling the reader to pick something from a set number of choices (like from a list or dropdown menu), and use âchooseâ when youâre telling the reader to make a choice thatâs more open-ended (such as, âChoose what kind of store you want to openâ).
-
-
-
-#### Do
-
-- From the **Products** drop-down menu, select the one you want to discount.
-
-#### Donât
-
-- From the **Products** drop-down menu, choose the one you want to discount.
-
-
-
-Use consistent phrasing when referring to the readerâs choice. Use the most direct âIf you want toâ instead of more formal options such as âIf you would like toâ or âIf you wish to.â
-
-
-
-#### Do
-
-- If you want to add a product, then click **Add product**.
-
-#### Donât
-
-- If youâd like to add a product, then click **Add product**.
-
-
-
-Avoid using âdesiredâ in place of the more direct âwant.â
-
-
-
-#### Do
-
-- Select the item that you want to add to the order.
-
-#### Donât
-
-- Select the desired item to add to the order.
-
-
-
----
-
-## Structure conditional statements
-
-For conditional cases, start the step with âifâ so the reader doesnât have to read the whole sentence only to find out that the condition doesn't apply to them. Always add a âthenâ after the condition to help the reader identify the condition and the outcome.
-
-
-
-#### Do
-
-- If you need Z, then click A, B, and C.
-
-#### Donât
-
-- Click A, B, and C if you need Z.
-
-
-
----
-
-## Clarify results of actions
-
-Show results of actions in the same step as the task and be clear about where in the flow the reader is. In general, omit results statements unless the result is surprising or unexpected.
-
-### Put actions and results in the same step
-
-If you need to mention the results of a user action, then do it in the same numbered step that describes that action (donât use a separate numbered step).
-
-### Mention earlier steps to reinforce order of tasks
-
-You can refer to an earlier step to reinforce the order of the steps.
-
-For progress within a series of steps, use the phrase âWhen youâveâ or âAfter youâve.â Avoid using âOnce youâve.â
-
-For progress between tasks, begin a section with âNow that youâveâ or âAfter youâveâ (referring back to the previous action or step).
-
-### Use âmake sureâ and âconfirmâ for important tasks
-
-When asking the reader to confirm something, use one of the following terms:
-
-- âMake sureâ in cases where thereâs still a related important task (instead of âcheck thatâ or âverify thatâ).
-- âConfirmâ in cases where the reader has already been told to do something, and youâre now reminding them.
-
-### Tips
-
-For instructions, use the command form of the verb.
-
-
-
-#### Do
-
-- Click **Refresh** to show your new orders.
-
-#### Donât
-
-- Clicking **Refresh** will show your new orders.
-
-
-
-Limit the future tense to cases that actually refer to the future.
-
-
-
-#### Do
-
-- Choose an end date. After this date, the boosted post will revert to a regular post.
-
-#### Donât
-
-- Click **Save**. The price will change when the discount is applied.
-
-
-
----
-
-## Use screenshots for clarity
-
-Screenshots help visual learners understand complex tasks and add context to the tasks youâre documenting. However, they often go out of date quickly and can be expensive to translate. Use them wisely.
-
-### Use screenshots for complex tasks
-
-In general, donât use a screenshot to illustrate every step in a task. Instead, save screenshots for places where the interface is complicated.
-
-### Focus on the specific area of the action
-
-Include only the most relevant section of the screen or admin in the screenshot. Avoid taking a screenshot of an entire page, because this increases the likelihood of the image going out of date quickly.
-
-### Make screenshots with equal margins
-
-When highlighting an area of a screenshot, try to show an equal amount of space around the area that you want the reader to focus on.
-
-### Use consistent images in a workflow
-
-Tell a story by being consistent with details in screenshots within a document.
-For example, you could follow a single order and keep the details the same from one screenshot to the next.
-
----
-
-## Teach through documentation
-
-Documentation is an opportunity for education. Building context, making instructions clear, and encouraging learning are key.
-
-### Link to next steps
-
-Offer links to the next steps. Choose the next steps based on reader profiles and feedback.
-
-### Encourage learning
-
-Encourage the reader to learn more. Explain the benefits of the feature in the introduction of your document.
-
-### Make the first tasks easier
-
-Where you can, give the readers âearly wins.â Make the first step or two of the task short and easy.
-
-### Build context
-
-Connect the current task to readersâ wider knowledge: other parts of Shopify, the store-building process, and even the business-building process.
-
-### Try not to repeat information on the same page
-
-In most cases, avoid repeating information on a page. You might need to repeat important points to make sure the reader notices them. For example, you might repeat a warning from the documentâs introduction within a set of instructions.
-
----
-
-## Use the right tone
-
-Think of the context that the reader is in and what they might be feeling and thinking while theyâre reading your documentation. This perspective will help you pick what type of tone to apply.
-
-### Instructional tone
-
-Most people donât want to spend time reading documentation. They want to learn what they need to know, and then move on. The language in documentation needs to be short, to the point, and task oriented. That doesnât mean your writing needs to be terse or dry.
-
-### Lighter tone
-
-In general, you can begin a document using a lighter tone.
-
-### Informal tone
-
-When you introduce a task, an informal tone can help draw the reader in, offer context, and encourage the reader to keep going. You can also use a more informal tone when introducing sub-tasks, to give the reader a break from the instructions.
-
-### Direct tone
-
-For actions and tasks, aim for a much more direct tone. Keep your tone approachable by using contractions (for example _canât_, _itâs_) to link directions and results.
-
-### Tips
-
-Use contractions.
-
-
-
-#### Do
-
-- After youâve set up your product, click **Save**.
-
-#### Donât
-
-- After you have set up your product, click **Save**.
-
-
-
-Address the reader or user as âyou.â
-
-
-
-#### Do
-
-- You can add products from the **Products** page in your Shopify admin.
-
-#### Donât
-
-- Products can be added from the Products page in your Shopify admin.
-
-
-
-Keep tone in check by avoiding the following:
-
-- Sounding patronizing, chummy, cheery, childish, or otherwise inappropriate in an attempt to seem informal and relatable.
-- Colloquialisms, jokes, sarcasm, jargon, and slang. Avoid anything thatâs too culturally specific.
-- Anything that causes the user to pause or hesitate, unless you explicitly want them to.
-
----
-
-## Use the active voice
-
-Use the active voice as much as possible, which generally sounds less formal than the passive voice. This means writing what merchants do, instead of what is being done by merchants. But in cases where the passive voice sounds more natural than the active voice, use passive voice (like with verbs such as âpublishâ or âassignâ and with nouns like âdiscountâ).
-
-
-
-#### Do
-
-- After youâve added a product, click **Save**.
-
-#### Donât
-
-- After the product has been added, **Save** must be clicked.
-
-
-
----
-
-## Improve readability
-
-Itâs important that your sentences flow nicely. Changing things up by combining or separating phrases and ideas will improve prose. Reading sentences that flow helps with reader comprehension.
-
-### Avoid choppy writing
-
-Use linking adverbs, conjunctions, and prepositions liberally to avoid choppy writing.
-
-
-
-#### Do
-
-- Click the button to open the window.
-
-#### Donât
-
-- Click the button. The window opens.
-
-
-
-### Place old or expected information first, and new information last
-
-Putting the context, expected information, or old information first helps reduce a reader's mental load while they read. When new information is first, it requires the reader to hold on to the information while trying to determine why it is relevant.
-
-
-
-#### Do
-
-- This feature is available for stores in the United States, Canada, and Mexico.
-
-#### Donât
-
-- Stores in the United States, Canada, and Mexico can use this feature.
-
-
-
-### Change up sentence structures
-
-Vary your sentence structure, especially in longer paragraphs. Try not to use more than two phrases with a âTo x, do yâ structure in a rowâthis gets repetitive and can cause the reader to lose interest. To break it up, add a short declarative sentence, if possible.
-
-### Break up complicated chunks
-
-Use conjunctions (a word that joins words or groups of words) to break up complicated passages.
diff --git a/polaris.shopify.com/content/content/inclusive-language.mdx b/polaris.shopify.com/content/content/inclusive-language.mdx
index a817c2d00bc..0e79949f55b 100644
--- a/polaris.shopify.com/content/content/inclusive-language.mdx
+++ b/polaris.shopify.com/content/content/inclusive-language.mdx
@@ -2,6 +2,7 @@
title: Inclusive language
description: Make commerce better for everyone by writing inclusively.
icon: EyeCheckMarkIcon
+order: 6
keywords:
- copy instructions
- copy rules
@@ -64,7 +65,7 @@ To write accessible content:
- Donât imply that those with disabilities are abnormal, less than, or âsufferingâ
- Avoid words associated with disabilities to describe objects, features, or experiences
-### Recommended language
+#### Recommended language
#### Disable, disabled
@@ -170,7 +171,7 @@ We want all merchants to feel comfortable participating in commerce. Even if uni
- 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
-### Recommended language
+#### Recommended language
#### Black hat, white hat (hacking)
@@ -277,11 +278,11 @@ Avoid using this term, as many associate it with the institution of slavery.
Gender is an important part of many peopleâs identity. Stereotypes and assumptions about gender can make their way into product experiences and leave people feeling excluded or misrepresented. When you do talk about gender, be intentional. Only use gendered language if it makes your content more inclusive and accurate.
-### Internationalization
+#### Internationalization
Many languages lack ungendered options, like the English âthey.â When possible, write in a way that avoids gendered language. For example, write âyouâ instead of a third person pronoun. You may need to work with a translator to avoid unintentionally gendering concepts. Always choose the clearest option.
-### Recommended language
+#### Recommended language
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.
diff --git a/polaris.shopify.com/content/content/index.mdx b/polaris.shopify.com/content/content/index.mdx
index 18e51b2add0..916d616b914 100644
--- a/polaris.shopify.com/content/content/index.mdx
+++ b/polaris.shopify.com/content/content/index.mdx
@@ -1,7 +1,7 @@
---
title: Content
order: 4
-description: Thoughtful, consistent interface content is a core element of a well-designed user experience.
+description: Thoughtful, crafted content is a core element of a well-designed user experience
icon: TextAlignmentLeftIcon
---
diff --git a/polaris.shopify.com/content/content/merchant-to-customer.mdx b/polaris.shopify.com/content/content/merchant-to-customer.mdx
deleted file mode 100644
index 7f544c612f6..00000000000
--- a/polaris.shopify.com/content/content/merchant-to-customer.mdx
+++ /dev/null
@@ -1,276 +0,0 @@
----
-title: Merchant-to-customer content
-description: Shopify creates content for different audiences. One of those audiences is merchantsâ customers. A customer is a person or organization who interacts with a Shopify merchant or a merchantâs sales channel.
-icon: EmailNewsletterIcon
-keywords:
- - merchant to buyer
- - buyer
- - shopper
- - buyer voice and tone
- - customer voice and tone
- - writing for checkout
- - checkout
- - check out
----
-
-# {frontmatter.title}
-
-{frontmatter.description}
-
-Merchant-to-customer content represents the merchant, not Shopify, and should optimize the customersâ online or retail store experience.
-
-Every UX discipline is encouraged to create content at Shopify. Use this guide when youâre writing content that a customer will see on a Shopify store or receive from a merchant.
-
-Youâll find merchant-to-customer content in places such as:
-
-- Online store checkout pages
-- Shipping update emails
-- Return labels and emails
-- Point of Sale (POS) screens, such as digital receipts and payment errors
-
----
-
-## What it isnât
-
-If you write for multiple audiences, itâs important to note that merchant-to-customer content isnât:
-
-- Shopify-to-buyer content, such as Shopify Pay or Arrive
-- Shopify-to-merchant content, such as the Shopify admin
-- Shopify-to-world content, such as shopify.com or blog posts
-
----
-
-## Experience values for customers
-
-Shopify has a set of [experience values](https://polaris.shopify.com/foundations/experience-values). The ones to focus on when creating merchant-to-customer content are:
-
-### Considerate
-
-Wherever and however a customer uses a Shopify experience (even if they donât know itâs Shopify), we want it to work for them. The best Shopify experiences work on every screen, on every platform, in every language, and in every country.
-
-### Efficient
-
-Shopify experiences help customers achieve goals faster, more accurately, and with less effort. We break complex tasks down into simple steps, use friction to highlight important decisions, and always set expectations about what will happen next.
-
-### Trustworthy
-
-Shopify experiences are genuine, always honest, and transparent. We show customers that merchants act in the customerâs best interest. We create communication that strengthens the trust customers have in merchants.
-
----
-
-## Merchant voice and tone
-
-Merchant voice and tone is customer-focused.
-
-Shopify merchants sell everything from physical products, such as eco-sneakers, to digital products, like music downloads. The language they use is very different from store to store. This means that when writing from a merchant perspective, we use a voice thatâs appropriate on any store, and for any type of customer. Merchant-to-customer content shouldnât sound out of place coming from any merchant.
-
-### Human, but not individual
-
-Too much personality is inappropriate for some stores. Customers arenât going through the purchase experience to admire the witty content. Research shows that the majority of people want content thatâs easy to understand and communicates concepts efficiently. Not robotic. Not full of personality. Just clear and straightforward to help them complete their task.
-
-Keep in mind that some content, such as emails, can be personalized by merchants. Youâre providing a default for them to work from.
-
-
-
-#### Do
-
-- Your payment details couldnât be verified. Check your card details and try again.
-- All transactions are secure and encrypted.
-- Select the address that matches your card or payment method.
-- Thanks!
-
- This example is when the customer finishes checkout in person (all other examples are from online checkout).
-
-#### Donât
-
-- A fatal error occurred.
-
-Whoops! Houston, we have a problem!
-
-- Donât worry, your details are safe with us!
-- Address must correspond with that held by your payment provider.
-- Thanks for stopping by! or See you again soon!
-
-
-
-### Shopping, not ecommerce: use shopper terms
-
-Avoid technical or ecommerce terms. Customers are interested in their order and their delivery, not in inventory and fulfillment. They might want to sign up for news and exclusive offers, but not marketing emails.
-
-
-
-#### Do
-
-- Enter your name exactly as itâs written on your card.
-- Youâll get shipping and delivery updates by email.
-
-#### Donât
-
-- There was a server verification error with your payment provider.
-- Weâll inform you when weâve fulfilled your order.
-
-
-
-### Concise, but not short
-
-Itâs important that any purchase flow is efficient. Use short, easy-to-understand words and phrases. For example:
-
-
-
-#### Do
-
-- Use âtoâ
-- Use âgo toâ
-- There was a problem with our payments
-
-#### Donât
-
-- Donât use âin order toâ
-- Donât use âproceed toâ
-- No payment gateway is currently configured
-
-
-
-But remember that clear beats short. Donât use content that can be interpreted in different ways. For example, does âbi-weeklyâ mean twice a week or every two weeks? Itâs clearer to say âEvery 2 weeks.â Using more words is okay if it provides clarity.
-
-
-
-#### Do
-
-- Every two weeks
-- Getting available shipping rates
-
-#### Donât
-
-- Bi-weekly
-- Loading
-
-
-
-No matter who the audience is, all Shopify content follows the same [grammar and mechanics](https://polaris.shopify.com/content/grammar-and-mechanics) and [product content guidelines](https://polaris.shopify.com/content/product-content).
-
-Read our general [voice and tone guidelines](https://polaris.shopify.com/content/voice-and-tone) to compare how Shopify talks to merchants.
-
----
-
-## Vocabulary considerations
-
-âBuyerâ and âcustomerâ are similar so itâs easy to confuse the use of these terms.
-
-A âbuyerâ interacts with multiple Shopify stores or has a direct relationship with Shopify, such as through Shopify Pay.
-
-In contrast, a âcustomerâ is a person or organization who interacts with a Shopify merchant or a merchantâs sales channel.
-
-In the Shopify admin and Point-of-Sale (POS), a customer appears on the Customers page when they engage with a merchant in an identifiable way. This could be because they:
-
-- were added or imported by the merchant
-- started a purchase but abandoned it at checkout
-- made a purchase
-- create a customer account
-- subscribed to the merchant's mailing list
-
-Word usage to use/avoid:
-
-
-
-#### Do
-
-- Use the store name in place of âmerchantâ
-- Be direct and use âyouâ
-- Focus on the merchant-to-customer relationship
-- Use âtext messageâ or âmessageâ when writing for North American audiences
-- Use noun + verb phrases for success messages, for example, âpayment sentâ
-- There was a problem with our payments
-
-#### Donât
-
-- Merchant (in place of store name)
-- Customer or customer (in place of âyouâ)
-- Shopify (keep Shopify out of the conversation)
-- SMS
-- Oh happy day! (donât be over-congratulatory)
-- Wrong, fail, failure, error (avoid sounding robotic or negative)
-
-
-
-### Common terms
-
-Use the following terms to refer to common concepts and actions within the merchant-to-customer experience.
-
-Note: all of these terms should be lowercase, unless they're a proper noun or the first word in a sentence.
-
-#### cart
-
-The page that displays an order summary. Customers see this page before they proceed to checkout.
-
-#### checkout
-
-The customer experience for paying for items and completing an order.
-
-#### delivery
-
-How an order reaches the customer. Delivery covers more than just shipping. For example, customers can choose whether the order is shipped to their delivery address or picked up in-store.
-
-#### discount code
-
-A dollar amount, percentage, or code that dictates how much a product will be reduced in price.
-
-#### duties
-
-Additional costs that may be incurred on orders that are delivered internationally. Duties may be incorporated into the shipping cost.
-
-#### gift card
-
-A type of product with monetary value that merchants can either sell to customers or issue to them as a gift, reward, or incentive.
-
-#### item
-
-One unit of a product on an order.
-
-#### login
-
-The credentials that a customer uses to access their account.
-
-#### order
-
-The term for a purchase. Donât say package, or add unnecessary words like sales order.
-
-#### payment
-
-Describes a specific way a customer can pay such as Visa, MasterCard, or Apple Pay.
-
-#### pay now
-
-This text is displayed on Call To Action (CTA) buttons that trigger a payment. On free orders, this is replaced with âComplete orderâ.
-
-#### pickup
-
-A delivery option where customers physically collect an order.
-
-#### return
-
-A transaction where a customer sends a product back to the store for an exchange or refund. A refund is part of a return.
-
-#### refund
-
-The funds that a customer receives from a merchant, for example, when returning an item.
-
-#### shipping
-
-How a merchant sends an order to a customer. Also known as the shipping method.
-
-#### subtotal
-
-The cost of the items on an order before additional charges, such as tax and shipping.
-
-#### total
-
-The cost of the items on an order after additional charges such as tax and shipping.
-
-#### you
-
-A way of referring to the customer that's checking out. Use you, or use the name that the customer has provided.
-
-#### we
-
-A way of referring to the store name. Most of the time, refer to the store by name. However, you can use âweâ when using the store name would sound overly wordy or insincere.
diff --git a/polaris.shopify.com/content/content/naming.mdx b/polaris.shopify.com/content/content/naming.mdx
index 0cb0bc5e4ad..777af8fd82e 100644
--- a/polaris.shopify.com/content/content/naming.mdx
+++ b/polaris.shopify.com/content/content/naming.mdx
@@ -1,7 +1,8 @@
---
title: Naming
-description: The names we give our products and features teach merchants how to use Shopify and how to find the things they need to run their business.
+description: What to consider as you name products and features
icon: ProductIcon
+order: 4
keywords:
- names
- caps
@@ -76,7 +77,7 @@ If thereâs room, describe the feature instead of defaulting to only using the
-### Using âShopifyâ
+#### Using âShopifyâ
Only Shopify can use the word âShopifyâ in a name. The word âShopifyâ canât be used to name third-party products.
@@ -151,7 +152,7 @@ There are two types of approaches to naming, the descriptive approach, or the ev
If youâre a Shopify employee and are looking to trademark an evocative name, ask the legal department for help.
-### Descriptive names
+#### Descriptive names
Features and products connected to Shopifyâs main product offering should have names that reveal something about their purpose. Avoid jargon and make sure the name you pick wonât get confused with similar names or terms.
@@ -202,7 +203,7 @@ Avoid jargon and give merchants a hint about the actions theyâll be able to ta
-### Evocative names
+#### Evocative names
Standalone products use evocative names to position us in the industry. These unique and bold naming conventions can help with branding or recall, but donât always help people understand the experience. Theyâre better for standalone products, and not for experiences that are part of Shopifyâs main product offering.
@@ -284,7 +285,7 @@ A good product or feature name should:
There are two types of approaches to naming, the
[descriptive approach, or the evocative approach](/content/naming#descriptive-vs-evocative-names).
-### Referring to Shopify and areas in the admin
+#### Referring to Shopify and areas in the admin
Use consistent and easy to understand descriptions when referring to locations in product, especially in [help documentation](/content/help-documentation#navigation). Descriptive feature names arenât [capitalized](/content/naming#general-guidelines), but when providing steps in a workflow, itâs okay to capitalize the page name, for example, âGo to the Products pageâ. Note that the page name is capitalized, but âpageâ isnât.
@@ -351,7 +352,7 @@ Top-level marketing content is created for audiences who have little context abo
-### Using âappâ and âchannelâ
+#### Using âappâ and âchannelâ
For app names in areas with surrounding context, like in the app store or on the
Apps page in the Shopify admin, donât add the word âappâ to the end of the name.
@@ -449,7 +450,7 @@ If thereâs room for a description, explain the channel type.
In general, capitalize evocative names and donât capitalize feature names. Avoid acronyms, and think about how your audience will interpret a name.
-### Capitalization
+#### Capitalization
Donât capitalize default features. Default features are built into Shopify and merchants donât have to sign up, add, or opt in to use them. Analytics and discounts are examples of default features.
@@ -504,7 +505,7 @@ Names shouldnât be capitalized if they:
-### Acronyms and abbreviations
+#### Acronyms and abbreviations
An acronym is a word formed from parts of an existing compound term. For example, ârich text editorâ could be written as âRTEâ. An abbreviation is a shortened form of a written word or phrase used in place of the whole word or phrase. âAmtâ is an abbreviation for âamountâ.
@@ -604,7 +605,7 @@ When using a country as an adjective (such as when referring to currency), you m
-### Similar names
+#### Similar names
Being an ecommerce platform has its naming challenges. For example, a lot of feature names could include the word âshippingâ or âpayâ. Think merchant-first and be descriptive to differentiate the name. Imagine what itâs like to have conversations with merchants about similar names like Shopify Payments or around our pricing plans to identify names that might be confusing. Before naming a new product or feature:
@@ -612,7 +613,7 @@ Being an ecommerce platform has its naming challenges. For example, a lot of fea
- Ask the support team to see if they think itâll conflict with another name
- Draft a test conversation around similar sounding names
-### Localization and translation
+#### Localization and translation
Names may not translate directly to other languages. Identify if you need to create a separate name, or if a direct translation will do.
@@ -651,7 +652,7 @@ Use SMS when writing for Indian and Nordic audiences.
-### Initials
+#### Initials
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.
diff --git a/polaris.shopify.com/content/content/product-content.mdx b/polaris.shopify.com/content/content/product-content.mdx
deleted file mode 100644
index b1d5df77233..00000000000
--- a/polaris.shopify.com/content/content/product-content.mdx
+++ /dev/null
@@ -1,73 +0,0 @@
----
-title: Product content
-description: Thoughtful, consistent interface content is a core element of a well-designed user experience.
-icon: TextInColumnsIcon
-keywords:
- - content standards
- - content guidelines
- - content strategy practices
- - interface content
- - strategic language
- - edit content
- - editing content
- - reading level
- - writes
- - writing
- - writing tips
- - language tips
- - content tips
- - designing
- - strategic designing
- - action
- - consistency
- - consistent
- - writing public-facing text
- - public-facing text
- - writing public-facing copy
- - public-facing copy
- - writing public-facing content
- - public-facing content
----
-
-# {frontmatter.title}
-
-{frontmatter.description}
-
-Our content standards will help you understand how to think strategically about the language in your products and apps. Theyâll also give you clear, tactical suggestions designed to help you use language to craft better experiences.
-
-[Each component](/components) also includes content guidelines about how to write for specific interface elements.
-
-## Respond to merchant needs
-
-Not everyone is a confident writer, but everyone can improve their content by making sure it responds to the needs of their audience. Keep in mind that real people rely on Shopify every day to run their businesses. The product, feature, or app youâre building can make a big difference to the people using it. Take some time to learn about who they are, what they need, and the language they use.
-
-- Only use industry-standard terminology when you have reason to believe it will improve understanding. Spend time researching what words people use, rather than defaulting to what corporations call things.
-- Edit unnecessary or repeated words.
-- Write for small screens first. Constraints can help you focus on the most important message.
-- Read your content out loud. If you get tripped up or it doesnât sound like something a human would say, your content needs to be edited.
-
----
-
-## Encourage action
-
-People use Shopify to get things done, whether theyâre managing a store, or making a purchase. Content should be written and structured to help the reader understand and take the most important actions.
-
-### Tips
-
-- Calls to action on buttons and links should start with a strong verb that describes the action a person will take when they click.
-- Always prioritize the most important information and task â donât make people dig to find what they care about. toBreak down complicated tasks into steps that help people focus on one thing at a time.
-- Use the [active voice](/content/grammar-and-mechanics#basics) to clarify the subject and the action.
-
----
-
-## Be consistent
-
-To help your audience understand key concepts and actions they can take, use consistent nouns (words used to identify people, places, or things) and verbs
-(action words) wherever possible.
-
-### Tips
-
-- Get in the habit of making a list of all the most important verbs and nouns in the experience youâre building.
-- Look at your word list. Does each word clearly describe the object or action it represents in the simplest way possible?
-- Does your language reflect how people think and the words they use?
-- Identify synonyms (a word or phrase that means exactly or nearly the same as another word or phrase in the same language), and eliminate them. Each important object and action should have a single word to represent it.
diff --git a/polaris.shopify.com/content/content/voice-and-tone.mdx b/polaris.shopify.com/content/content/voice-and-tone.mdx
deleted file mode 100644
index 09cc1f78446..00000000000
--- a/polaris.shopify.com/content/content/voice-and-tone.mdx
+++ /dev/null
@@ -1,386 +0,0 @@
----
-title: Voice and tone
-description: Learn how to apply Shopifyâs voice and choose the right tone, no matter what product, feature, or app youâre building.
-icon: ChatIcon
-keywords:
- - sound like Shopify
- - personality of Shopify
- - brand personality
- - empathy
- - merchant feelings
- - merchant emotions
- - merchant context
- - content voice
- - content tone
----
-
-# {frontmatter.title}
-
-{frontmatter.description}
-
-## What are voice and tone?
-
-Shopifyâs voice is a reflection of who we are. We should always sound like
-Shopify.
-
-At the same time, some aspects of our personality might be more or less apparent, depending on the audience and their context. Thatâs tone.
-
----
-
-## Shopifyâs voice
-
-Our voice is a reflection of who we are. So who are we?
-
-**Simply put, weâre a company, built by real people who understand this business and care about helping others succeed.**
-
-**That should be clear every time someone uses our products or services.**
-
-Most often, we show this through well-crafted tools that help people get their jobs done efficiently. But there are times when our personalities and perspectives should be more apparent. In those times, we should adapt our tone to respond to people in an appropriate and meaningful way.
-
-You'll find more specific guidelines on how to adapt your tone to different situations in this guide.
-
----
-
-## Voice guidelines
-
-As Shopifyâs voice, we should always:
-
-### Be real, but not too tough or overly familiar
-
-- Use business casual languageâbe plain-spoken, not pretentious or overly playful
-- Be upfront and honest with merchants, even if we make a mistake
-- Communicate with clarity and empathyâbe direct, not insensitive
-
-### Be proactive, but not needy or pushy
-
-- Offer merchants sincere encouragement and practical advice
-- Clearly explain how merchants are impacted when something goes wrong, but donât overexplain with redundant content
-
-### Be dynamic, but not scattered or impulsive
-
-- Communicate in a way that respects merchant emotion and context
-- Avoid words that generalize success like âevery,â âall,â and âmostâ
-- Use language that supports action, movement, and progress
-
-### Guide, but donât handhold or prescribe
-
-- Use expertise to help merchants succeed; donât talk down to them
-- Be specific when explaining benefits without making things sound better than they are
-- Teach people the âwhyâ and âhowâ behind actionsâdonât just tell them to do something
-
----
-
-## Adapting tone by situation
-
-Our tone adapts to the context. Weâll use certain voice attributes more or less based on the situation.
-
-Often people frame tone guidance around adapting to the emotional state of the audience. The reality is we never know a personâs emotional state. Even when things seem the most positive, we canât be sure.
-
-While itâs helpful to consider how your audience is likely to feel, donât assume or tell them how to feel. Instead, focus on the specifics of the situation and less on the emotions. Here are some of the most common situations to consider.
-
-### Everyday tasks and activities
-
-When everything is working as it should, our goal is to give people what they need to get work done, without getting in the way or drawing attention to ourselves. We want the audience to know what something is or that something has happened as expected.
-
-
-
-#### Do
-
-Look for the simplest way to communicate informationâwords arenât always necessary.
-
-
-
-#### Donât
-
-Use overly complicated or intimidating language.
-
-
-
-
-
-
-
-#### Do
-
-Be consistent for identical actions or destinations when possible.
-
-- _Delete product_
-- _Delete collection_
-
-#### Donât
-
-Add extra text just to fill space.
-
-
-
-
-
-### Learning and education
-
-Sometimes it helps to give more explanation or education. In these situations, we want to make sure people feel confident in their actions and in our capabilities.
-
-Some people will want to be guided step-by-step through the process, while others may just want to try it out and learn on their own. Look for ways to give them both options.
-
-Remember, they may have sought this out specifically or we may have recommended it to them, so donât assume that they want or need to use it.
-
-
-
-#### Do
-
-Help people understand why they should do something, not just how.
-
-
-
-#### Donât
-
-Oversell or overpromise.
-
-_Create a new campaign and you could double your sales this holiday season._
-
-
-
-
-
-#### Do
-
-Break down complicated tasks into steps that help people focus on one thing at a time.
-
-
-
-#### Donât
-
-Be overly prescriptive about how someone should use a feature.
-
-_You need to add at least 10 products before opening your store._
-
-
-
-### Simple errors
-
-While we do our best to be proactive and protect against unexpected events, they still happen. These are often simple mistakes or roadblocks to action that can easily be fixed. Although they arenât necessarily errors or problems, they can feel that way at first.
-
-In this case, our job is to help people understand what happened so that they can get back to work as quickly as possible
-
-Read the [error message guidelines](https://polaris.shopify.com/patterns/error-messages) for more detailed guidance.
-
-
-
-#### Do
-
-Clearly explain the situation and how it can be resolved.
-
-_Product weight needs to be positive. Change the product weight to be greater than or equal to 0 and try again._
-
-#### Donât
-
-Use overly dramatic or scary words for simple errors.
-
-_Bad request, forbidden, fatal, expectation failed, unresolved, invalid_
-
-
-
-
-
-#### Do
-
-Look for ways to help people resolve problems automatically.
-
-
-
-#### Donât
-
-Use error numbers or code unless theyâre easily recognizable by people and help them solve the problem.
-
-
-
-
-
-### Acknowledging effort, progress, or completion
-
-There are situations where we want to acknowledge that someone completed a complex activity or difficult task.
-
-While we donât need to celebrate the accomplishment, we should recognize that they put in the time and effort. Depending on the level of effort, these may be simple confirmations or more active recognition that they completed something difficult.
-
-
-
-#### Do
-
-If this is a task people do regularly, make it clear that the step is complete in a simple and non-intrusive way, like a [App Bridge Toast](https://shopify.dev/docs/api/app-bridge-library/reference/toast). Consider ways to confirm completion without words or messaging.
-
-_Product saved_
-
-#### Donât
-
-Assume people are excited or celebrating. They may be annoyed if it was a particularly long process or if the immediate benefits arenât clear.
-
-_Congrats! You set up your single login for Shopify._
-
-
-
-
-
-#### Do
-
-If the task was something we initiated or required, thank them for their time.
-
-_Thanks for taking the time to share your feedback._
-
-#### Donât
-
-Refer to simple actions or completed steps as âsuccesses.â
-
-_You successfully added a product._
-
-
-
-### Motivate or encourage action
-
-These are situations when we want to keep people moving along a desired path. In most cases, we do that with direct information and clear steps to encourage action.
-
-We donât want to be too overzealous or action-driven hereâitâs more about helping people understand the next step and giving them the context they need to take it.
-
-
-
-#### Do
-
-Help people understand what the next steps are and why they should take them.
-
-_Your email address is connected to 8 accounts. Set up a single login to switch between stores faster and log in less often._
-
-#### Donât
-
-Assume the next step or outcome is guaranteed.
-
-_Youâre just a few steps away from receiving your first order._
-
-
-
-
-
-#### Do
-
-Provide guidance to help people understand if the decision is right for them.
-
-_Based on your type of business, this is the POS hardware we recommend:._
-
-
-
-### Serious problems or errors
-
-There are times when we need to share bad news. This might be an outage or an error, or it may be a product that weâre no longer supporting. These are hopefully rare situations, but they will happen.
-
-In this case, thereâs a serious risk of damaging trust and hurting our relationship with the audience, so we should be very careful about how we communicate.
-
-Read the [error message guidelines](https://polaris.shopify.com/patterns/error-messages) for more detailed guidance.
-
-
-
-#### Do
-
-Explain the impact on their business clearly, without using confusing or scary language.
-
-_Some of todayâs sales data hasnât been updated yet. This will be fixed shortly. Your data is safe, and your sales are not affected._
-
-#### Donât
-
-Ask merchants to trust us without providing data or context.
-
-_Todayâs sales data might not be accurate, but donât worryâitâs just temporary._
-
-
-
-
-
-#### Do
-
-Apologize and empathize when weâre at fault, but within reason.
-
-_All systems are now fully operational. We recognize and apologize for the stress, concern, and impact this outage had on your business. In the coming days we will be working to fully understand how this widespread internet infrastructure failure affected our platform._
-
-
-
-
-
-#### Do
-
-Provide clear steps to resolve issues. If thereâs no solution, be direct about what that means for the merchant and what weâre doing about it.
-
-_Your Shopify Payments account is on hold. Please attach your State Tax Exemption Certificate for review._
-
-
-
-### Announcing new features and updates
-
-Itâs exciting to launch a new feature or update, but always consider the audienceâs perspective first. While we may be excited about the benefits and capabilities, change can be intimidating or annoying for users.
-
-When youâre announcing something new, focus on educating and explaining what it is, what itâs used for, and what the user can expect.
-
-
-
-#### Do
-
-Pitch our product by explaining the specific merchant benefits.
-
-_**Introducing the new Buy Button**_
-
-_Make it your own with custom fonts, colors, and styles. It also loads 50% faster so your visitors wonât miss it._
-
-#### Donât
-
-Just talk about ourselves and assume the experience for merchants will be easy.
-
-_**Get Shopifyâs new Buy Button**_
-
-_Itâs never been easier to customize the fonts, colors, and styles of Buy Buttons. Itâs also twice as fast._
-
-
-
-
-
-#### Do
-
-If possible, let users dismiss announcements or postpone changes until theyâre ready.
-
-
-
-
-
-### Celebrations and congratulations
-
-There are occasionally times when we want to celebrate an event or milestone, or to congratulate someone for an important accomplishment. In reality, this should be one of the least common situations we encounter.
-
-Let audiences know that we understand that itâs an important moment and weâre excited for them, but be careful not to take credit for it. Even if we played a role in their success, this isnât about us.
-
-Remember, this is about celebrating their accomplishments, not ours. Launching something new? You probably donât need to celebrate with them. Read our guidance around [announcing new features and updates](#announcing-features).
-
-
-
-#### Do
-
-Only celebrate truly important or monumental situations when the audience likely feels proud, excited, or satisfied.
-
-_Your store is 1 year old today! Hereâs to many more._
-
-#### Donât
-
-Celebrate completing tasks or processes that people donât actually want to celebrate. Did they finish something difficult or do something for us? You may want to acknowledge their effort instead.
-
-_You set up your payment providers, congrats!_
-
-
-
-
-
-#### Do
-
-Express genuine happiness for merchants. Recognize their accomplishment and congratulate them on a job well done.
-
-_You launched your store! Nice work._
-
-#### Donât
-
-Take credit for merchantsâ successes or presume to know what they need.
-
-_We did it! Congrats on your first sale._
-
-
diff --git a/polaris.shopify.com/next.config.js b/polaris.shopify.com/next.config.js
index 86505045646..35956a3b522 100644
--- a/polaris.shopify.com/next.config.js
+++ b/polaris.shopify.com/next.config.js
@@ -149,6 +149,26 @@ const nextConfig = {
destination: '/coming-soon/view-transitions',
permanent: false,
},
+ {
+ source: '/content/product-content',
+ destination: '/content/fundamentals',
+ permanent: true,
+ },
+ {
+ source: '/content/actionable-language',
+ destination: '/content/fundamentals',
+ permanent: true,
+ },
+ {
+ source: '/content/help-content',
+ destination: '/content/fundamentals',
+ permanent: true,
+ },
+ {
+ source: '/content/help-documentation',
+ destination: '/content/fundamentals',
+ permanent: true,
+ },
...whatsNew,
...actions,
...deprecated,