Tips for Creating Effective Technical Documentation for Your Shopify App

Writing technical documentation may not be your favorite part of being an app developer, but it’s an important aspect of supporting your app users. In this article, we dive into top tips to help you write more effective, helpful docs.

Not many developers actually enjoy writing technical documentation—they'd rather be coding! But sometimes documentation is a necessary part of what you deliver. These tips will help you create effective content to support your merchant-facing Shopify app.

Before diving in, though, let's clarify what we mean by documentation. Here, we're going to look at some high-level concepts around creating articles or topics to accompany your app: additional content that helps merchants get started with your app, can teach them how to use it, and helps them if they run into any trouble. It's often called the help, or the docs.

Although this type of documentation is separate from your app, it's best to consider it as integral to your overall offering—in other words, treat it with the same care and respect that you use to design and code the app itself. Your technical documentation also works like a marketing tool: it shows your professionalism, reflects the quality of your app, and can increase adoption of your app.

1. Minimize the need for documentation with a solid UX

A well-designed app will have a great user experience, and many of its features will be easy to figure out just by looking at it. This is good! The less documentation you have to write, the better. And the fewer docs that a merchant needs to read, all the better for them.

The words in the app itself, which are often called user interface text, are critical—these are the words that the merchants using your app will see, and that will guide them every time they use it.

This user interface text is a type of documentation in itself. An app typically has fields where a merchant can enter data, buttons to click, and so on. Make sure all these user interface elements have helpful labels so it's crystal clear what a field is for.

If the labels aren't enough to convey exactly what needs to be done in a particular part of your app, you can include short lines of text in your app to explain what to do in a specific screen or area. The Shop app, for example, uses short explanations for the following settings:

The Shop app’s short pieces of copy to explain to users what settings do.

The combination of the label and the additional text makes it clear what the specific settings are for. 

We won't go into any more details about this type of documentation, but check out the Shopify Polaris guidelines for great information about building the most effective user interface content for your app.

In general, though, the better your app is documented in the user interface itself, the easier it will be for merchants to use, and you'll have less need for accompanying technical documentation.

You might also like: UX Writing: 10 Tips for Crafting Effective Content.

2. Always keep the user of your apps—Shopify merchants—in mind

Just as you design your apps for merchants, design your documentation for merchants too. 

"Just as you design your apps for merchants, design your documentation for merchants too."

For example, your app is likely designed with certain expectations about what the user already knows, whether it be about inventory, marketing, shipping, or some other aspect of running a business. Your docs should use the same language that merchants are familiar with in their day to day work.

This can be best shown with an example of a topic heading. Imagine you have created an app that helps with a particular aspect of handling online returns and exchanges. Now imagine the merchant encountering this heading for a topic in your docs:

Certification of products resubmitted to the place of selling

Huh? This almost sounds like a really bad translation. What if it was this instead:

Authorizing product returns

That makes much more sense! The revised heading uses language that merchants understand and likely use daily. Someone skimming your documentation will immediately know what this topic covers.

Make sure the words that you're using in your docs are common and meaningful to merchants.

"Make sure the words that you're using in your docs are common and meaningful to merchants."

The same goes for technical jargon. As a developer, you probably are quite familiar with terms like APIs, methods, and error logs, for example. But many merchants do not know what those terms mean or how they are relevant to using your app, so avoid them in your content.

A good example of documentation that uses language of merchants is the Launchpad content in the Shopify Help Center. Its very first line explains what this Shopify Plus app does and the specific merchant activities that it's designed for:

Launchpad’s clear, merchant-friendly wording.

This advice of keeping your audience in mind might sound simple and obvious, but it's actually really easy to fall into the trap of writing what you know, rather than what your audience needs to know. We'll touch on this again later.

3. Start writing your docs as soon as you start to code

Some people think that writing documentation starts after the coding is done. After all, how can you possibly explain how to use an app if it isn't built yet, right?

Nope! It's actually really important to start writing much earlier than that. Documentation turns out best when it's treated like code: prototype, throw away as needed, iterate, and improve.

The first pass of your docs will be far from perfect, and that's okay. What's important is to start getting your ideas written down so that you can then rewrite, edit, and rewrite some more, again and again—just like the way you work on making your code accomplish its goals and run error-free.

"The first pass of your docs will be far from perfect, and that's okay. What's important is to start getting your ideas written down so that you can then rewrite, edit, and rewrite some more, again and again—just like the way you work on making your code accomplish its goals and run error-free."

If you have the resources, it's often a good idea to get someone who hasn't helped to develop the app to write the docs. For example, a professional technical writer or content designer can devise and write the content for you. But even if you hire someone to do the writing, get them involved with your project as early as possible so that they have enough context. For more information on this, you can check out my article on Medium, Is your technical writer a garnish, or a main ingredient?

You might also like: 10 Myths About Prototyping, Busted.

4. Create task-based documentation

To paraphrase an old saying, you can create two different types of documentation for something: how it works, and how to work it.

How it works documentation tends to be more technical and is usually more like reference material for the technically-inclined. This is also sometimes called feature-centric content.

But what you should create for your app is content that explains how to work it. In other words, provide instructions that will show merchants how to use your app to achieve their end goals. This is often called task-based documentation.

"Provide instructions that will show merchants how to use your app to achieve their end goals."

After a merchant adds your app to their Shopify store, they want it to solve a problem for them. But depending on what your app does, they might first have to do some configuration of the app, transfer some data into it, or otherwise set it up so that it can start doing its thing.

Those are the first tasks you can focus on writing about: configuring and setting up the app for their specific needs.

Then, you can move on to the next tasks they'll need to do to use the app.

To give you a better idea of what the two contrasting types of content are, here is an example. Feature-centric docs might have a topic called "CSV file structure" that describes the columns that are in a comma-separated values file and the data types for each column, and a topic called "CSV exports" that goes over how the data in that file can be used by another system.

In contrast, task-based docs might have topics with headings like these:

• Add your products to the CSV file
• Verify the products in the CSV file
• Export your inventory to another system

Notice how here, even on their own, the headings convey in helpful language the tasks that the merchant might want to do. They also use task-oriented words and terms that a merchant is likely familiar with.

Merchants are usually going to be happier with task-based docs. Most of the Shopify Help Center uses task-based content, as this example of topics for the Kit app shows:

The topics in our Kit documentation.

You might also like: 5 Key Strategies to Improve Your App Support.

5. Get your docs reviewed and tested by someone else

Your documentation needs to be reviewed and tested with as much care as the app itself. And it's important that you get people who aren't very familiar with your app to do some of that reviewing. Don't rely on just yourself!

A huge benefit of having someone else review your docs is that they aren't an expert about your app. By being somewhat removed from the development process, an independent reviewer won't have all the knowledge that you do, and therefore won't make assumptions that you might make. This is sometimes called the "curse of knowledge." To learn more about this concept, see Wikipedia or Steven Pinker's book The Sense of Style.

In summary, though, if you leave the review to yourself, you can be subtly influenced by your expertise with the app and the content you've written. In contrast, if someone comes in with fresh eyes, they'll have a greater chance of noticing if a more task-oriented approach is needed, gaps where additional documentation could be helpful, out of date information, and even the odd typo that you might not see.

Your documentation will always benefit from a review by someone in addition to the developers.

Great documentation means happy users

Creating documentation for an app might not be the top or favorite thing on your to-do list, but it's really worth the effort to create great docs that will help merchants use your app effectively.

The tips in this article just skim the surface of all that's involved in creating technical documentation. If you want to dig deeper, here a few further resources to explore:

• Write the Docs is an organization that has a wealth of information on their site, including a Documentation Guide.
• Google offers some introductory technical writing courses at https://developers.google.com/tech-writing.
• Strategic Writing for UX by Torrey Podmajersky focuses on user interface content but covers a lot in a slim book.
• Bold Commerce creates a number of Shopify apps with accompanying content. Check out their approach to documentation.

However you go about creating your docs, remember to focus on your merchants' goals, keep the language simple and direct, and be sure to get someone else to review your technical documentation before you publish it.