An app documentation guide helps users understand VTEX apps, including installation and configuration.
To add documentation to an app, you must use the Docs builder. The documentation is written in Markdown files, inside the app repository. By using the Docs builder, the documentation becomes publicly available on the VTEX Developer Portal.
In this guide, you’ll learn about the available template, general guidelines, and examples of Onboarding articles.
This guide is part of the App Store guidelines and one of the requirements to submit an app to the homologation process and make it available in the App Store.
Writing app documentation
Target audience
Description: Identify your readers
| ✅ Do | ❌ Don’t |
|---|---|
| Differentiate between developers and business users. | Assume a single audience. |
Learning objective
Description: Define the user's takeaway.
| ✅ Do | ❌ Don’t |
|---|---|
| Clearly state what users should learn. | Leave learning goals ambiguous. |
Title
Description: Use a clear and concise title.
| ✅ Do | ❌ Don’t |
|---|---|
| Include punctuation, version numbers, or the word App. |
Introduction
Description: Briefly introduce the app and its benefits.
| ✅ Do | ❌ Don’t |
|---|---|
| Focus solely on technical details. |
Before you begin (optional)
Description: List requirements before installation.
| ✅ Do | ❌ Don’t |
|---|---|
| Write lengthy paragraphs explaining prerequisites. |
Installation
Description: Provide a step-by-step guide with code snippets (if applicable).
| ✅ Do | ❌ Don’t |
|---|---|
| Skip steps or lack specific instructions. |
Configuration
Description: Guide users through the app configuration.
| ✅ Do | ❌ Don’t |
|---|---|
| List all essential settings with detailed steps as defined in the settingsSchema. | Omit configuration details. |
How it works
Description: (Optional) Detail the app functions and provide steps for using the app.
| ✅ Do | ❌ Don’t |
|---|---|
| Skip steps or lack specific instructions. |
Customization
Description: (Optional) Provide steps for customizing the app.
| ✅ Do | ❌ Don’t |
|---|---|
| Ignore customization options. |
Contributors
Description: (Optional) Acknowledge contributors.
| ✅ Do | ❌ Don’t |
|---|---|
| Follow the All-Contributors specification. | Omit recognition of contributors. |
Callouts
Description: (Optional) Acknowledge contributors.
| ✅ Do | ❌ Don’t |
|---|---|
| Highlight information using callouts. | Use the provided callout types (Information, Warning, Danger) with appropriate messages. |
App documentation template
App documentation template
# {Insert the app name}
`\\{insert app name\\}` `\\{app's purpose starting with a verb\\}` so you can `\\{job to be done\\}`.
## Before you begin
You need to have `\\{insert what the user needs to have: an account in another platform, CLI, knowledge about another app, etc.\\}`.
If you don't have `\\{insert what the user needs to have and how to get it\\}`.
## Installation
1. [Install](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-installing-an-app) the `\\{insert app name\\}` app in the desired VTEX account by running `vtex install \\{appVendor\\}.\\{appName\\}` in your terminal.
2. (Optional, for frontend apps) Open the store Store Theme app directory in your code editor.
3. (Optional, for frontend apps) Open the app `manifest.json file` and add the `\\{insert app name\\}` app under the `peerDependencies` field.
"peerDependencies": {
"vtex.{appName}": "{appVersion}"
}
4. (Optional, for frontend apps) Declare the `\\{insert app name\\}` app in the desired template. For example:
"store.home": {
"blocks": [
+ "{app-name}",
]
},
**
## Configuration
Once you have installed the app, you can `\\{describe the app's configuration in the VTEX Admin as defined in the settingsSchema[https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest#settingsschema], for example\\}`.
1. `First step`.
2. `Second step`.
3. `Third step`.
## Customization (Optional, for frontend apps)
To apply CSS customizations to this and other blocks, follow the instructions in [Using CSS Handles for store customization](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-using-css-handles-for-store-customization).
| CSS Handles |
| ------------------ |
| csshandlesName |
| csshandlesName |
| csshandlesName |
## How the app works (optional)
Use this section for [Admin apps](https://learn.vtex.com/docs/course-admin-lang-en) when the app requires user interaction beyond the Admin configuration.
`\\{Detail what can be done with the app and provide the steps to perform each operation.\}\`
## Contributors
Thanks go to these wonderful people:
- `\\{insert the GitHub username\\}`
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome.