--- title: Style Guide slug: style-guide icon: {"faIcon":"fa-solid fa-arrow-down-z-a"} docTags: createdAt: 2023-12-06T13:23:20.390Z --- ## Visão Geral Bem-vindo(a) ao nosso Style Guide — a bússola essencial para a criação de documentações claras, coerentes e eficazes na nossa plataforma. Este guia foi cuidadosamente elaborado para garantir que todas as informações técnicas sejam comunicadas de maneira padronizada e acessível, facilitando tanto o trabalho dos redatores quanto a compreensão dos usuários. Ao adotar este guia, você assegurará que os documentos mantenham um alto padrão de qualidade e consistência, refletindo a nossa dedicação em oferecer uma experiência excepcional. Cada seção do Style Guide é projetada para orientar a estruturação, o estilo, a formatação e o design da nossa documentação técnica. Vamos juntos construir um acervo de informações valioso e confiável, que capacite nossos usuários a explorar plenamente as capacidades da nossa plataforma. Este é o primeiro passo na sua jornada para criar conteúdo técnico que não apenas informa, mas também engaja. ## Estrutura Geral 1. **Introdução (Objetivo/Resumo)**: - Comece com uma breve introdução, focando no objetivo e na utilidade da funcionalidade ou produto. 2. **Instruções Detalhadas**: - Siga com instruções passo a passo detalhadas, explicando cada etapa do processo. 3. **Imagens Ilustrativas**: - Enriqueça a documentação com **imagens, vídeos e GIFs** que exemplifiquem claramente as etapas descritas. - (por exemplo, 50x100 para imagens, resolução otimizada para vídeos e GIFs para carregamento rápido). - Quando possível, incorpore **vídeos curtos** para demonstrar processos ou funcionalidades complexas e utilize GIFs para mostrar sequências de ações de forma dinâmica e fácil de acompanhar. - Adicione legendas descritivas e textos alternativos a todas as imagens. - Lembre-se de que o uso de recursos visuais deve complementar o texto, oferecendo uma visão geral mais rica e uma experiência de aprendizado mais interativa. 4. **Parametrização e Configuração**: - Detalhe as opções de parametrização e configuração disponíveis, explicando cada campo e sua função. 5. **Exemplos Práticos**: - Forneça exemplos práticos de como a funcionalidade ou produto pode ser utilizado. 6. **Finalização**: - Encerre com informações sobre como verificar o resultado ou o impacto da ação realizada. Para ilustrar melhor, sugerimos observar a seguinte imagem: ::Image[ ]{src="https://api.archbee.com/api/optimize/G1NTw6yAi4RDUYbsU8csp/Njh1kHAEzQji-fed-1Zpt_image.png" size="86" width="2020" height="1294" position="center" darkWidth="2020" darkHeight="1294" showCaption="false"} Nela temos um resumo das diretrizes que devemos seguir no momento de elaborar uma nova documentação para nossos usuários. Tente responder o máximo das perguntas descritas acima para uma documentação mais completa. ## Estilo de Conteúdo 1. **Linguagem Clara e Objetiva**: - Use uma linguagem clara e objetiva, evitando jargões técnicos desnecessários. 2. **Tom Informativo e Acessível**: - Mantenha um tom informativo e acessível, apropriado para usuários de diversos níveis de habilidade técnica. 3. **Foco no Usuário**: - Concentre-se em como a funcionalidade ou produto atende às necessidades do usuário. # Visão Geral para Documentação de Conectores A seção de documentação de conectores é dedicada a fornecer informações específicas e detalhadas sobre cada conector individual disponível na nossa plataforma. Esta seção serve como um guia para usuários entenderem como configurar, usar e integrar conectores específicos com seus fluxos de trabalho e sistemas externos. ## Orientações Específicas para Conectores ### Versão da API Ao documentar um conector, é essencial incluir a versão da API do serviço ao qual o conector se integra. As APIs podem ser atualizadas ou alteradas com o tempo, e especificar a versão ajuda a garantir que os usuários estejam alinhados com as funcionalidades corretas e os métodos suportados. Aqui estão as orientações para incluir a versão da API: 1. **Localização da Versão**: A versão da API deve ser claramente mencionada no início da documentação do conector para fácil referência, sempre colocando a URL da documentação caso esteja disponível online. 2. **Compatibilidade**: Esclareça quais versões do conector são compatíveis com as versões da API. 3. **Atualizações e Mudanças**: Se a versão da API for atualizada, atualize a documentação do conector para refletir quaisquer novas funcionalidades ou mudanças críticas. ## Formatação e Design 1. **Consistência Visual**: - Mantenha a consistência visual em toda a documentação, especialmente em termos de tamanhos de imagem e layout. Iniciar a documentação com *Texto com header H1*, em seguida, cada seção interna com *header H2*, e assim por diante. Documentação separadas por diferentes níveis de cabeçalho/*header* facilitam o entendimento e a tabela de conteúdo (*table of contents* à direita na tela): - Para títulos principais usar **H1** - Para título das seções usar **H2** - Para demais tópicos **H3** 2. **Uso de Templates e Exemplos**: - Inclua templates e exemplos de código sempre que apropriado, garantindo que sejam claramente identificáveis e fáceis de seguir. - Para seções com código de qualquer linguagem usar o comando ***(code) ***após isso, basta selecionar a linguagem desejada. 3. **Observações e destaques:** - Para destacar, alertar ou fazer uma observação específica sobre um assunto, use o comando */callout *para criar uma caixa de texto destacada. Esse componente conta com 4 modos: **Info**, **Sucesso**, **Alerta** e **Perigo**. Selecione o modo adequado com o que deseja trazer de informação ou alerta. ### Exemplos de Formatação e Design: :::Heading{depth="1" indent="1"} Texto H1 para o título da página ou quebra de conteúdos muito densos. ::: :::Heading{depth="2" indent="1"} Texto H2 para subtítulos dentro do mesmo assunto iniciado em H1. Exemplo: Criando a conexão, Na prática. ::: :::Heading{depth="3" indent="1"} Texto H3 para os títulos específicos dentro do tema H2, por exemplo, os nomes dos Recursos de um conector: Clientes, Cobranças, etc. ::: Abaixo o campo de código: ```javascript ``` Abaixo exemplo de callout de Info: :::hint{type="info"} ::: ## Feedback e Ação 1. **Encorajamento à Prática**: - Incentive os usuários a aplicarem o conhecimento adquirido através de exemplos práticos. 2. **Links para Recursos Adicionais**: - Forneça links para recursos adicionais, como tutoriais em vídeo e seções de análise de problemas, para fornecer suporte e assistência complementar. ## Conclusão As conclusões devem resumir os principais pontos da página, destacando os resultados ou próximos passos esperados. Recomenda-se evitar repetição de informações, mantendo uma linguagem objetiva e convidando o leitor para ações futuras ou a consulta de referências adicionais.