Documentação de aplicativos

Templates

A documentação de apps ajuda os usuários a entender os aplicativos VTEX, incluindo sua instalação e configuração.

Para adicionar documentação a um aplicativo, você deve usar o Docs builder. A documentação é escrita em arquivos Markdown, dentro do repositório do aplicativo. Ao usar o Docs builder, a documentação fica disponível publicamente no VTEX Developer Portal.

Neste guia, serão apresentadas diretrizes gerais, modelos e exemplos de artigos de integração.

Este guia faz parte das diretrizes da App Store e é um dos requisitos para enviar um app para o processo de homologação e disponibilizá-lo na App Store.

Como escrever uma documentação de aplicativo

Público-alvo

Descrição: Identifique seus leitores.

✅ Correto	❌ Incorreto
Diferencie entre desenvolvedores e usuários administradores.	Considere um único público.

Objetivos de aprendizagem

Descrição: Defina o que o usuário deve aprender.

✅ Correto	❌ Incorreto
Indique claramente o que os usuários devem aprender.	Deixe os objetivos de aprendizagem ambíguos.

Título

Descrição: Use um título claro e conciso.

✅ Correto	❌ Incorreto
Use o nome do aplicativo e um verbo que descreva o objetivo de aprendizagem. Escreva a primeira letra de cada palavra em maiúscula.	Inclua pontuação, números de versão ou a palavra `App`.

Introdução

Descrição: Apresente brevemente o aplicativo e seus benefícios.

✅ Correto	❌ Incorreto
Resuma a finalidade do aplicativo e os benefícios para o usuário. Inclua uma imagem e callouts para observações importantes.	Foque exclusivamente nos detalhes técnicos.

Antes de começar (opcional)

Descrição: Liste os requisitos antes da instalação.

✅ Correto	❌ Incorreto
Use itens de lista ou uma checklist. Use callouts, se aplicável.	Escreva parágrafos longos explicando os pré-requisitos.

Instalação

Descrição: Escreva um guia passo a passo com trechos de código (se aplicável).

✅ Correto	❌ Incorreto
Organize em etapas claras e concisas. Aumente a clareza com trechos de código.	Pule etapas ou não forneça instruções específicas.

Configuração

Descrição: Oriente os usuários na configuração do aplicativo.

✅ Correto	❌ Incorreto
Liste todas as configurações essenciais com etapas detalhadas, conforme definido no settingsSchema.	Omita detalhes de configuração.

Como funciona

Descrição: (Opcional) Detalhe as funções do aplicativo e as etapas para usá-lo.

✅ Correto	❌ Incorreto
Use listas numeradas para cada operação, com etapas claras e concisas. Use imagens para ilustrar a interface do usuário.	Pule etapas ou omita instruções específicas.

Personalização

Descrição: (Opcional) Escreva as etapas para personalizar o aplicativo.

✅ Correto	❌ Incorreto
Inclua identificadores CSS e uma tabela relacionada, se aplicável. Consulte a documentação externa para personalização CSS.	Ignore as opções de personalização.

Colaboradores

Descrição: (Opcional) Inclua um agradecimento aos colaboradores.

✅ Correto	❌ Incorreto
Siga a especificação All Contributors.	Omita o reconhecimento dos colaboradores.

Callouts

Descrição: (Opcional) Inclua um agradecimento aos colaboradores.

✅ Correto	❌ Incorreto
Destaque informações usando callouts.	Use os tipos de callout fornecidos (Information, Warning, Danger) com mensagens apropriadas. Use texto genérico para destacar informações.

Modelo de documentação de um aplicativo

Modelo de documentação de um aplicativo


# `{Insira o nome do aplicativo}`
`{insira nome do aplicativo}` `{finalidade do aplicativo começando com um verbo}` para que você possa `{tarefa a ser realizada}`.
![adicione-uma-pré-visualização-da-imagem](/)
## Antes de começar
Você precisa ter `{insira o que o usuário precisa ter: uma conta em outra plataforma, CLI, conhecimento sobre outro aplicativo, etc.}`.
Se você não tiver `{insira o que o usuário precisa ter e como obtê-lo}`.
## Instalação
1. [Instale](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-installing-an-app) o aplicativo `{insira o nome do aplicativo}` na conta VTEX desejada executando `vtex install {appVendor}.{appName}` no seu terminal.
2. (Opcional, para aplicativos frontend) Abra o diretório do aplicativo Store Theme da loja no seu editor de código.
3. (Opcional, para aplicativos frontend) Abra o arquivo `manifest.json` do aplicativo e adicione o aplicativo `{insira o nome do aplicativo}` no campo `peerDependencies`.
      "peerDependencies": {
          "vtex.{appName}": "{appVersion}"
      }
      
4. (Opcional, para aplicativos frontend) Declare o aplicativo `{insira o nome do aplicativo}` no modelo desejado. Por exemplo:
      "store.home": {
          "blocos": [
      +     "{app-name}",
          ]
      },
*![adicione-uma-pré-visualização-da-imagem](/)*
## Configuração
Depois de instalar o aplicativo, você pode `{descrever a configuração do aplicativo no Admin VTEX, conforme definido no settingsSchema[https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest#settingsschema], por exemplo}`.
1. `Primeiro passo`.
2. `Segundo passo`.
3. `Terceiro passo`.
## Personalização (opcional, para aplicativos frontend)
Para aplicar personalizações CSS a este e outros blocos, siga as instruções em [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 |
## Como o aplicativo funciona (opcional)
Use esta seção para [aplicativos do Admin](https://learn.vtex.com/docs/course-admin-lang-en) quando o aplicativo exigir interação do usuário além da configuração de administrador.
`{Informe em detalhes o que pode ser feito com o aplicativo e forneça as etapas para realizar cada operação.}`
## Colaboradores
Agradecemos a colaboração destas pessoas incríveis:
- `{insira o nome de usuário do GitHub}`
Este projeto segue a especificação [All Contributors](https://github.com/all-contributors/all-contributors). Todas as contribuições são bem-vindas.

Como escrever uma documentação de aplicativo

Modelo de documentação de um aplicativo

Exemplos de artigos de documentação de aplicativos