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.
Here’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.
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
- 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.