Help documentation

After you build an app or other integration, writing help documentation will show merchants how to use it.

These guidelines are based on our experience writing help documentation for the Shopify Help Center. They’re all intended to serve the same goal: to educate and empower Shopify merchants.

If you want to share a link to help documentation from in your app, use the Footer help component.


Plan for your audience

The way you write your help documentation should change depending on the type of audience and their expectations. Take some time to plan for your audience.

Audience types

Write help documentation for its intended audience. For any given document, we can expect a wide spectrum of Shopify users as an audience:

Prospective users

  • Not signed up yet, possibly on a free trial

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
  • Able to 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 will likely have 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

  • Lots of hand-holding
  • 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 to-the-point)
  • Code fragments
  • Pointers to information sources

This is just one way to imagine the variety of users that fit into our audience. However we imagine their skill level, our aim for documentation remains the same: to accommodate a wide range of users and their objectives. We can do this by presenting information in a way that’s inclusive of different skill levels, different learning styles, and different workflows.


Use headings to organize your document

Readers come to help documentation with different expectations and in different usage settings. For example:

  • One might be working through a long, multi-stage setup process to connect a third-party app into her admin
  • Another might be using her tablet to check out the details of Shopify POS and see if it could be used at her cafe
  • Another might be trying to make a quick edit to his storefront in the half hour he has left before going to pick up his kids from school

In all these different cases, the reader needs documentation that’s findable, usable, and relevant—in short, organized.

Effective headings

Effective headings make it clear to readers which sections of a document are most relevant to their current tasks (findability). Headings also provide them with a good sense of progress while they move from one task to the next (usability).

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 (ing-word) based statements.

  • Creating products from your admin

  • Create products from your admin

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

  • Add a customer

  • Adding a customer

Avoid pronouns and articles in headings to keep them short.

  • Connecting Facebook accounts

  • Connecting a Facebook account

  • Connecting your Facebook account

Avoid long strings of nouns in a heading.

  • Posting products

  • Creating posts

  • Creating product posts

  • Creating product post pages

Keep the key descriptors close to the front of a heading to make the heading easier to scan quickly. Don’t bury them under “How to”, or “To”, for example.

  • Add a product

  • How to add a product

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

  • Boost a post, Choose an audience, Fulfill an order

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

  • Add a product

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

  • Adding products to your store

  • Adding Products To Your Store.

Use parallel structure in lists, headings, and pretty much everywhere else to encourage comprehension and recall.

  • Adding products to your store, Deleting products from your store, Editing products in your store

  • 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. Readers aren’t there to read a spec: they want to keep their businesses up and running.

  • Use this feature to keep track of key updates and promotions.

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

  • In the Pinterest section, click Remove channel.

  • 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 (like “Choose what kind of store you want to open”).

  • From the Products drop-down menu, select the one you want to discount.

  • 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…”

  • If you want to add a product, click Add product.

  • If you’d like to add a product, click Add product.

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

  • Select the item you want to add to the order.

  • 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 does not apply to them. It often helps to add a “then” to help the reader identify the condition and the outcome.

  • If you need Z, then click A, B, and C.

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

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). In general, omit results statements unless the result is surprising or unexpected.

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:

  • “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.

  • Click Refresh to show your new orders.

  • Clicking Refresh will show your new orders.

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

  • Choose an end date. After this date, the boosted post will revert to a regular post.

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

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.

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.

  • After you’ve set up your product, click Save.

  • After you have set up your product, click Save.

Address the reader or user as “you.”

  • You can add products from the Products page in your Shopify admin.

  • 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 the merchant does” instead of “what is being done by the merchant.” But in cases where the passive voice sounds more natural than the active voice, go ahead and use passive voice (like with verbs such as “publish” or “assign” and with nouns like “discount”).

  • After you’ve added a product, click Save.

  • After the product has been added, Save must be clicked.


Improve readability

It’s important that the sentences you put together flow. Changing things up and knowing when things should be combined or separated will improve prose. Reading sentences that flow helps reader comprehension.

Avoid choppy writing

Use linking adverbs, conjunctions, and prepositions liberally to avoid choppy writing.

  • Click the button to open the window.

  • Click the button. The window opens.

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.