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 theShopify Help Center. They’re all intended to serve the same goal: to educate and empower Shopify merchants.

To include a link to help documentation in your app or channel, use theFooter helpcomponent.

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.

有效的标题

有效的标题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.

Do

Creating products from your admin

Don’t

Create products from your admin

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

Do

Add a customer

Don’t

Adding a customer

Avoid pronouns and articles in headings to keep them short.

Do

Connecting Facebook accounts

Don’t

Connecting a Facebook account
Connecting your Facebook account

Avoid long strings of nouns in a heading.

Do

Posting products
Creating posts

Don’t

Creating product posts
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 lists, headings, and pretty much everywhere else 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. Readers aren’t there to read a spec: they want to keep their businesses up and running.

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

From your Shopify admin, clickProducts.
ClickAdd a product.

Don’t

From your Shopify admin, clickProducts, clickAdd 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, clickRemove channel.

Don’t

Find the Pinterest section, then clickRemove 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”).

Do

From theProductsdrop-down menu, select the one you want to discount.

Don’t

From theProductsdrop-down menu, choose the one you want to discount.

使用一致的措辞指读er’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, clickAdd product.

Don’t

If you’d like to add a product, clickAdd product.

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

Do

Select the item 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 does not apply to them. It often helps to add a “then” 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.

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:

“确保”还有一个相关的情况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

ClickRefreshto show your new orders.

Don’t

ClickingRefreshwill 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

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

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 examplecan’t,it’s) to link directions and results.

Tips

Use contractions.

Do

After you’ve set up your product, clickSave.

Don’t

After you have set up your product, clickSave.

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.
任何导致用户to pause or hesitate, unless you explicitly want them to.

Use the active voice

尽可能多使用主动语态,通用电气nerally 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, clickSave.

Don’t

After the product has been added,Savemust 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.

Do

Click the button to open the window.

Don’t

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.