Help documentation

These are the core guidelines used to produce the Shopify Help Center, 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 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.

For task-based headings within the document, use imperatives.

Avoid pronouns in headings.

Avoid long strings of nouns in a heading.

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.”

Try to keep parallel grammatical structure between headings of the same level.

In most cases, headings should be statements rather than questions. Save question-style headings for FAQs or low-level headings that address specific functions.

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.

Use parallel structure in your content, such as in lists and headings, to encourage comprehension and recall.

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.

In general, avoid grouping multiple actions together in a single numbered step. Each step should include only one or two user actions.

Avoid telling the user to “find” or “locate” something in a task.

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”).

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.”

Avoid using “desired” in place of the more direct “want.”

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.

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.

Limit the future tense to cases that actually refer to the future.

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.

Address the reader or user as “you.”

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”).

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.

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.

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.