This article contains guidelines for writing documentation for Thinkific App Store apps. You have a great app — let's make sure everyone knows how to use it!
In this article
- How It Works
- Basic Requirements
- Recommended Structure
- Useful Links and Articles
- Best Practices
- Frequently Asked Questions
How It Works
In order to get your app approved and listed in the Thinkific App Store, you must have user-facing documentation that provides some basic details about your application: what it does, how it works, and how to install, configure, and uninstall it. While some of these processes can be covered by linking to Thinkific documentation, there will always be details specific to your application that you need to communicate to the end user: Thinkific's course creators. Writing good documentation is an opportunity to make your app shine: to make its value and operation clear to the user, while also smoothing over any potential bumps they might encounter when first learning how to use its features.
While your documentation can be as detailed as you want, there are some basic topics we highly recommend you cover:
- Basic description of your app: What it does, and how it will help the course creator
- How to use the app: Step-by-step instructions for the basic use case of your app
- How to install: Installation instructions and any specific or advanced set-up requirements
- How to configure: What settings are available (if any), what they do, and where to access them
- How to uninstall: Uninstallation instructions, and details about how uninstalling might affect their site or course content that was making use of the app.
- Support contact: Provide an email address and/or phone number where a course creator can contact you if they need additional help, or run into problems with the app.
You should structure your documentation in whatever way makes the most sense for the app, and any related products. However, if you're not sure what that is, or you need a place to start, consider using the basic structure provided below:
|(Optional) What is Thinkific||Include this section only if your users are likely to discover your app outside of the context of the Thinkific App Store, or if your app integrates with a number of different platforms. You can also link directly to our help article.|
|What is [App Name]?||An overview of your app and what it can help the user do.|
|How does [App Name] Work?||Details about what the app does, and how it does it.|
|How will [App Name] Affect my Thinkific Site?||Describe what effects your app will have within Thinkific. Will it add Site Builder sections? Will it add options for managing Coupons? Will it replace existing functionality?|
|How to Install [App Name]||Step-by-step instructions for installing your app. Include screen captures or videos for any tricky steps.|
|(Optional) Configuring [App Name]||If your app has different options or settings, explain what they are and where/how to change them.|
|How to Use [App Name]||Step-by-step instructions for your app's basic use case. If this section is long, or your app has multiple use-cases, we recommend creating a separate article for each case. Link them from the main article!|
|How to Uninstall [App Name]||Step-by-step instructions for uninstalling your app. If uninstalling your app will result in possible data loss or otherwise has the potential to create problems, make sure you are extremely clear about what will happen.|
|FAQ||Any frequently-asked questions about the app that come up, or that you expect to come up.|
When should I create separate articles?
Depending on the complexity of your app, you may need more than one article to usefully describe all the things it can do. If your main help article is longer than a page or two, consider breaking out some of the sections into their own article, and linking to that article from the main one. Good candidates for their own article include:
- Installing Your App
- Uninstalling Your App
- How to Do Specific Things
Useful Links and Articles
While writing your documentation, you should be sure to take full advantage of Thinkific's existing documentation: there's no need to reinvent the wheel! Reading and linking to articles that relate to your app can provide crucial context for you and your users. It can also help ensure that you are using Thinkific-specific terminology — such as the names of features, UI elements, and particular types of data — in order to build on the existing knowledge of your users. We recommend linking to any articles that deal with a feature your app interacts with directly. For example, if your app adds sections to Site Builder themes, you could link to our article on Adding a Site Builder Section. There are also some general articles about Thinkific Apps that your users may find helpful:
Writing can be hard, especially if it's not your day job. Here's a few short pieces of advice to keep in mind, and a couple of helpful resources: Always keep your reader in mind. Your software may make perfect sense to you, but the people using it won't have the same background and technical knowledge that you do. Getting a friend or non-technical colleague to read your documentation can help overcome any blind spots. Be consistent. Use the same names for things throughout your documentation, whether it's a UI element or how you refer to students. Whenever possible, adopt terminology the user is already familiar with; e.g. by using similar terms to Thinkific's documentation. When in doubt, look it up. There are lots of good resources out there for grammar and writing advice. Here are a couple:
- Tools like Grammarly or the AP Style Guide are handy for questions about basic grammar and punctuation.
- The Good Docs Project has some open-source resources and templates.
- Mailchimp's Style Guide has some solid general advice, though you should ignore the brand-specific instructions.
Frequently Asked Questions
Can I get someone at Thinkific to review my documentation before I submit it?
Unfortunately, we don't have the resources to provide an in-depth review to every piece of app documentation. All apps submitted to our App Store go through a review process, where we will make sure you have essential details like contact information included in your documentation; however, you are responsible for the quality of your documentation. It can be really helpful to reach out to one of your customers or someone who is not familiar with your app and ask them to install the app while referring to your documentation. This is a great way to catch anything that might have been overlooked!
I know that I need documentation, but I'm really struggling to get it done — and I'd much rather be coding cool apps! Help?
We sympathize — writing is hard! If you're really struggling, or just have other things to do, you may want to consider hiring a professional technical writer. Upwork.com is a good place to start looking.