Style Guide
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.
- 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.
- 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.
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.
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.
- 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, Sucesso, Alerta e Perigo. Selecione o modo adequado com o que deseja trazer de informação ou alerta.
Abaixo o campo de código:
Abaixo exemplo de callout de Info:
- 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.
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.
