A documentação da VTEX foi pensada para fornecer informações claras e concisas para qualquer pessoa interessada em usar ou integrar nossos produtos. Nosso objetivo é capacitar clientes e parceiros, oferecendo recursos que auxiliem no aprendizado sobre a plataforma e no desenvolvimento de negócios.
Neste guia, apresentaremos como a VTEX cria documentação e como você pode contribuir.
Recursos de aprendizagem
Na VTEX, oferecemos recursos onde você pode encontrar guias, tutoriais, trilhas de aprendizagem, atualizações de produtos e também fazer perguntas ou oferecer ajuda sobre os produtos VTEX:
| Nome do portal | Descrição |
|---|---|
| Help Center | Oferece tutoriais para iniciantes, guias de referência e artigos. |
| Developer Portal | Fornece informações sobre integrações, APIs e recursos de desenvolvimento para sua loja. |
| Community | Permite se conectar com outros usuários, fazer perguntas e compartilhar conhecimento dentro do ecossistema VTEX. |
| Learning VTEX | Oferece um ambiente de aprendizagem para desenvolver uma loja usando o Store Framework ou um VTEX App. |
Melhores práticas para escrever documentação
Na VTEX, nosso objetivo com a documentação é torná-la o mais simples e clara possível para os usuários que trabalham com ou têm interesse em soluções VTEX.
Aceitamos contribuições para a documentação da VTEX e incentivamos você a ajudar a melhorar a experiência do usuário. Existem várias maneiras de contribuir, dependendo do portal de documentação e do método que preferir. Consulte nossas Diretrizes de contribuição para mais informações.
Defina a estrutura da documentação
Antes de começar a escrever, é importante entender o público-alvo e os objetivos específicos da sua documentação. Para ajudar a definir os objetivos da documentação, responda às perguntas a seguir:
- O que você deseja que os usuários consigam fazer depois de ler sua documentação?
- Quais são as tarefas ou conceitos essenciais que eles precisam compreender?
- Que informações adicionais poderiam melhorar a experiência de aprendizagem do usuário?
Identifique o público
Para ajudar a definir o público, responda às perguntas a seguir:
- Quem é o público-alvo dessas informações?
- O que essas pessoas estão tentando fazer?
Na VTEX, temos os seguintes perfis de público como leitores da nossa documentação:
| Tipo de público | Descrição |
|---|---|
| Iniciante | Novo em operações de ecommerce e na VTEX, com pouca ou nenhuma experiência prévia. Seu principal desafio é se adaptar à plataforma e ao contexto do ecommerce. |
| Operacional | Lida com tarefas diárias de ecommerce, como cadastro de SKUs e gerenciamento de promoções. É familiarizado com o contexto de ecommerce, mas pode encontrar problemas que não consegue resolver sozinho. |
| Altamente técnico | Cria ou integra soluções técnicas com a VTEX. Trabalha na implementação de lojas, no desenvolvimento de aplicativos com nossas soluções e na integração com sistemas parceiros por meio das APIs da VTEX. Esse público precisa de documentação técnica detalhada que descreva as características de todos os nossos recursos e indique como atender às necessidades de negócio. |
Checklist para definir os objetivos da documentação
Para ajudar você a definir o contexto da documentação, siga a checklist abaixo:
Público
- Iniciante
- Operacional
- Altamente técnico
Categoria de aprendizagem
- Consciência - O público consegue descrever ou parafrasear um conceito ou uma funcionalidade.
- Compreensão - O público entende um conceito que auxilia a tomada de decisão.
- Habilidade prática - O público segue instruções para concluir uma tarefa.
Objetivo de aprendizagem
- Escolha uma ou duas tarefas ou conceitos que o conteúdo irá abordar. O que alguém deve conseguir fazer ou entender após ler este artigo?
- Exemplo de modelo: "Crie um guia sobre
{adicione o objetivo do guia}. O guia deve enfatizar clareza, estrutura e facilidade de uso e ter como público-alvo{adicione o público-alvo do guia}".
Princípios das diretrizes de documentação
Esta diretriz representa a interpretação da VTEX sobre a disciplina de estilística e explica determinadas escolhas linguísticas ao criar conteúdo funcional e técnico sobre nossa plataforma.
| Princípio | Orientação | Uso |
|---|---|---|
| Clareza e concisão |
|
|
| Consistência | Mantenha a consistência na terminologia, estilo e formatação em toda a documentação. | Use a mesma terminologia para conceitos semelhantes que se referem ao mesmo assunto/leitor de forma consistente do início ao fim do texto (exemplo: mantenha cliente em vez de consumidor e use você em vez de alternar com usuário ou membro). |
| Integralidade | Garanta que a documentação seja ao mesmo tempo completa e concisa, cobrindo todos os tópicos relevantes com o nível adequado de detalhe. | Se estiver documentando uma funcionalidade, inclua informações sobre como usá-la, casos de uso comuns e possíveis etapas de solução de problemas. |
| Usabilidade | Considere a perspectiva do usuário e escreva a documentação de forma que seja fácil de navegar e usar. | Use títulos, subtítulos e listas para organizar o conteúdo. |
| Fluxo lógico | Organize o conteúdo em uma sequência lógica e fácil de seguir. | Comece com uma introdução, seguida de seções detalhadas sobre tópicos específicos. |
| Mídia e exemplos de código | Use mídia como diagramas, capturas de tela e exemplos de código para ajudar na compreensão. | Use capturas de tela, diagramas e trechos de código para ilustrar exemplos e garantir precisão. Dica: diagramas, como os de arquitetura da plataforma ou do produto, podem ajudar a ilustrar processos ou relações complexas. |
Para mais informações sobre esses princípios, consulte as seções Grammar e Formatting.