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