Style Guide

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 introdução (objetivo/resumo) comece com uma breve introdução, focando no objetivo e na utilidade da funcionalidade ou produto instruções detalhadas siga com instruções passo a passo detalhadas, explicando cada etapa do processo 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 parametrização e configuração detalhe as opções de parametrização e configuração disponíveis, explicando cada campo e sua função exemplos práticos forneça exemplos práticos de como a funcionalidade ou produto pode ser utilizado 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 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 linguagem clara e objetiva use uma linguagem clara e objetiva, evitando jargões técnicos desnecessários tom informativo e acessível mantenha um tom informativo e acessível, apropriado para usuários de diversos níveis de habilidade técnica 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 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 compatibilidade esclareça quais versões do conector são compatíveis com as versões da api 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 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 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 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 info , sucesso sucesso , alerta alerta e perigo perigo selecione o modo adequado com o que deseja trazer de informação ou alerta exemplos de formatação e design texto h1 texto h2 texto h3 abaixo o campo de código abaixo exemplo de callout de info feedback e ação encorajamento à prática incentive os usuários a aplicarem o conhecimento adquirido através de exemplos práticos 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