App marketplace
29 May, 2019

6 mins

5 Must-Haves For Your App Marketplace Documentation

Developers are the lifeblood of your app marketplace, which is why you should strive to support them with the best documentation possible. While witty writing skills and cool features like night mode can improve your developer’s experience, what’s most important is that you include all the information developers will need to get started building their apps.

With that in mind, we’re dedicating this article to the five crucial sections your app marketplace documentation simply must include. If you can get all five of these parts in place, we’re confident that developers will be more likely to build apps for you, and have a better time doing so. So, without further ado, let’s dive into our five documentation must-haves!

1. High-Level About Page

A section that’s often forgotten on smaller app marketplaces is a high-level, plain English introduction. It should be written for both app developers and business decision makers. What you include in this section will depend on your audience, but nevertheless, we think it should be mandatory

One common element that all marketplace introductory pages should include is a list of benefits for contributing apps to the marketplace. Over at Shopify and DigitalOcean, they acknowledge that many developers are interested in creating a revenue stream with their applications. As such, both introductory pages make it abundantly clear that you can earn by creating applications.

App Marketplace Documentation - shopifyHere’s how Shopify’s high-level About page encourages potential developers to sign up.

On the other hand, Slack has identified that many developers will be using the app-building functionality to create internal integrations. As such, they focus their page on that context for app creation.

While all newly created Slack apps start their life installable only by your workspace, we recognize that the ultimate destiny of many, if not most, apps is to be used by your workspace exclusively.

It’s worth mentioning that an introductory page is more marketing material than a technical resource. To do a good job of this, you’ll want to have identified your target customers and what they’re looking to get from using your app marketplace.

Other elements you might include on this page are:

  • An explanation of what an app marketplace is and does, if you believe your audience might not know this
  • A breakdown of what functionality developers can leverage and what they might build with that
  • Quick links to statistics, case studies, and examples (especially for business-minded readers)

2. Getting Started

Next up on our list is a Getting Started page. We distinguish this from the high-level introductory page, as discussed above, in how it has a much more actionable nature. This page should be written for developers who’ve already decided to take the plunge and build an app. Some prospective developers may also want to read this page to see what’s involved in building an integration, so in addition, it should still be left open to the public.

There’s no set recipe for this page, either. Simply ask yourself what developers need to start building their integration. If developers need a license, as is true at Atlassian, here’s where you should introduce that. If developers will have the option to build distinct types of applications, this is a good time to explain that and link off to category-specific documentation. Otherwise, consider showing them how to set up a development environment and linking off to a reference of app and platform features they can leverage.

It’s worth mentioning that this isn’t something all app marketplace documentation websites do. Of the examples discussed in the previous section, both Shopify and DigitalOcean have separate Getting Started pages, but Shopify combines this with their broader introductory page. It’s entirely up to you whether to keep the two pages separate or combine them into one.

3. Platform Features

In the previous section, we suggested you link off to a reference of app and platform features that developers can build with. Whether you choose to mention this on your Getting Started page or not, some kind of reference material for your APIs is a definite must-have for your app marketplace documentation.

This shouldn’t need much explanation. To know what their possibilities are, developers need to know what data and functionality they can leverage with their apps and integrations. Make this information easily available to them, since it’s something developers will be coming back for time and time again.

App Marketplace Documentation - slack
Here’s a snapshot of Slack’s feature breakdown, where they introduce developers to individual functionalities.

In this section, you should explain, define, and give examples for API endpoints as would be done for any API documentation. It’s worth also mentioning that you may be able to generate a good amount of this documentation automatically if your APIs were built using a specification such as OpenAPI.

If you want to know more about getting this right, there’s a plethora of information on the web explaining how best to write API documentation.

4. Submission Guidelines

Let’s move back to more marketplace-specific docs elements. The fourth item on our list for app marketplace documentation must-haves is submission guidelines.

You’ll almost certainly put apps through a rigorous approval process before you let them onto your public app store. These submission guidelines are your chance to make your expectations clear, and their importance can’t be understated. If you’re thorough and upfront about what you want and need from developers, it will save you (and the developers) a huge amount of time down the line.

Here are some of the most frequent submission criteria included in app marketplace documentation — feel free to pick and choose from these and include them in your own guidelines:

  • The app requests only the necessary permissions
  • Apps are reasonably priced
  • It is well-built (i.e. it functions as described and does not break or excessively slow down the core platform)
  • It does not misuse or infringe on any copyright or trademark
  • The app is sufficiently unique to other apps on the marketplace
  • An acceptable amount of documentation is included
  • A privacy policy is included
  • Branded visual assets are included for the listing, including icons and screenshots
  • The correct category or categories for the app has been chosen

5. Payment Details

Last but not least, you should dedicate a portion of your app marketplace documentation to tackling all the formal, money-related aspects of the store. This includes topics like pricing, payment, and billing.

Like the Getting Started section, these formal details might also interest prospective developers. With that in mind, start from the top:

  • Can developers charge for their applications?
  • What pricing models can developers use to charge for their applications?
  • How much of the revenue will developers get to keep?

Beyond these basics, you may also want to discuss some of the more logistical aspects. For example, developers might like to know:

  • How often they’ll be paid
  • How they’ll be paid
  • What the relevant tax implications are (especially with regard to sales tax)

Final Thoughts on App Marketplace Documentation

There you have it: five essentials for your app marketplace documentation. From high-level introductory pages to nitty-gritty payment details, you’ll find that these sections cover almost everything developers need to know. Whether it’s business folk wanting to know what your marketplace can do for them or technical folk looking for the development essentials, you’ll have it covered! For more information on how you should write this content, be sure to check out our five steps to writing develop guides.

Related posts

Developer Communication Made Easy
Tools & Guides

Developer Communication Made Easy...

Communicating with developers both inside and outside your company can be hard (sorry, developers), so hard in fact you can...

What Is An App Marketplace?
Tools & Guides

What Is An App Marketplace?...

Table of ContentsWhat is an App Marketplace?What are the Parts of an App Marketplace?StorefrontDeveloper PortalAdministrator PortalExamples of App MarketplacesConsumer app...

Defining Your App Marketplace Requirements
Tools & Guides

Defining Your App Marketplace Requirements...

“Give me six hours to chop down a tree and I will spend the first four sharpening the axe.” –...