Documentação de Flowkits com IA
Visão Geral
A Fluid permite que você crie documentação técnica completa e padronizada automaticamente para seus Flowkits usando Inteligência Artificial. Esta funcionalidade economiza tempo, garante consistência e facilita o onboarding de novos membros da equipe.
O que é a documentação automática?
A documentação automática utiliza IA para analisar as configurações do seu Flowkit (nome, fluxos, conexões, parâmetros) e gerar um documento técnico estruturado em formato Markdown, seguindo as melhores práticas de documentação de software.
Benefícios:
- Economia de tempo: Documentação completa em ~10 segundos
- Padronização: Todas as documentações seguem o mesmo formato
- Completude: A IA garante que nenhuma informação importante seja esquecida
- Atualização fácil: Regenere sempre que fizer alterações no Flowkit
Como Acessar a Documentação
Existem duas formas de acessar a página de documentação de um Flowkit:
1. Durante a Criação/Edição
No Passo 5: Revisão do wizard de criação ou edição, você verá uma seção "Documentação" com um botão:
- Se não existir documentação: "Criar Documentação"
- Se já existir: "Editar Documentação"
Clique para ser direcionado à página de documentação.
2.Na página de detalhes
Na tela de detalhes do Flowkit, navegue até a tab "Documentação".
Gerando documentação com IA
Passo 1: Acessar o editor
- Acesse a página de documentação através de uma das formas descritas acima
- Você verá o editor de documentação com a barra de ferramentas no topo
Passo 2: Gerar com IA
- Clique no botão "Gerar com AI" na barra de ferramentas
- Um modal de confirmação será exibido informando:
- A IA criará uma documentação personalizada
- Serão considerados automaticamente:
- Nome e identificador do flowkit
- Todos os fluxos envolvidos
- Conexões configuradas
- Parâmetros definidos
- Clique em "Gerar Documentação"
- Aguarde aproximadamente 10 segundos
Atenção: Se o Flowkit já possuir documentação, ela será substituída pela nova versão.
Passo 3: Revisar e personalizar
Após a geração, a documentação aparecerá no editor. Ela incluirá:
- Visão Geral - Descrição, objetivo e categorias
- Conectores Necessários - Lista com conexões sugeridas
- Fluxos Incluídos - Detalhes de cada flow
- Parâmetros de Configuração - Tabela com tipos e descrições
- Como Ativar - Passo a passo para ativação
- Fluxo de Dados - Diagrama e exemplo prático
- Troubleshooting - Problemas comuns e soluções
- Informações Técnicas - Metadados e suporte
Você pode editar qualquer seção manualmente para adicionar informações específicas.
Passo 4: Salvar
Clique em "Salvar Documentação" no rodapé da página.
Estrutura da documentação gerada
A IA segue um template fixo com 8 seções obrigatórias:
# Nome do Flowkit
**Versão:** v1.0.0 | **Criado por:** Usuário | **Data:** DD/MM/YYYY
## 1. Visão Geral
[Descrição automática baseada no flowkit]
## 2. Conectores Necessários
[Tabela com conectores e conexões]
## 3. Fluxos Incluídos
[Lista detalhada de cada flow]
## 4. Parâmetros de Configuração
[Tabela com parâmetros obrigatórios/opcionais]
## 5. Como Ativar
[Passo a passo de ativação]
## 6. Fluxo de Dados
[Diagrama ASCII + exemplo prático]
## 7. Troubleshooting
[4 problemas comuns com soluções]
## 8. Informações Técnicas
[Metadados, monitoramento e suporte]Outras funcionalidades
Importar documentação (.md)
Se você já possui uma documentação em Markdown:
- Clique em "Importar .md"
- Selecione o arquivo .md do seu computador
- O conteúdo será carregado no editor
- Clique em "Salvar Documentação"
Regenerar documentação
Se você fez alterações no Flowkit (adicionou fluxos, mudou parâmetros):
- Acesse a página de documentação
- Clique em "Gerar com AI" novamente
- A IA criará uma versão atualizada com as novas informações
Validações e guardrails
A IA aplica validações automáticas para garantir qualidade:
Campos obrigatórios
- Nome do Flowkit não pode estar vazio
- Identificador (slug) deve estar em kebab-case
- Deve ter pelo menos 1 fluxo configurado
Limites de conteúdo
- Descrição do Flowkit: máximo 500 caracteres
- Descrição de cada Flow: máximo 200 caracteres
- Descrição de parâmetros: máximo 150 caracteres
- Conteúdo excedente é truncado com "..."
Fallbacks automáticos
- Se categorias vazias: "Não categorizado"
- Se casos de uso vazios: "Uso geral"
- Se versão inválida: "v1.0.0"
- Se conectores de flow vazios: "Nenhum conector"
Editor de documentação
A página de documentação possui um editor completo:
Sidebar (esquerda)
- Status: Indica se há documentação ou não
- Última edição: Timestamp da última modificação
- Metadados: Resumo do flowkit (fluxos, conexões, parâmetros)
- Ações rápidas: Botões de geração e importação
Editor principal
- Toolbar: Ações de geração, importação e exportação
- Modo Preview/Markdown: Alternar entre edição e visualização
- Syntax highlighting: Destaque de sintaxe Markdown
- Auto-save: (Opcional) Salvamento automático a cada 30s
Rodapé
- Cancelar: Descarta alterações e volta
- Salvar Documentação: Salva e atualiza o flowkit
Casos de uso comuns
Caso 1: Novo Flowkit sem documentação
- Crie um flowkit normalmente
- No Passo 5, clique "Criar Documentação"
- Na página de documentação, clique "Gerar com AI"
- Confirme no modal
- Revise e salve
Caso 2: Atualizar Flowkit existente
- Edite o flowkit (adicione flows, mude parâmetros)
- Salve as alterações
- Clique "Editar Documentação"
- Clique "Regenerar com AI"
- Documentação será atualizada automaticamente
Caso 3: Importar documentação externa
- Acesse a página de documentação
- Clique "Importar .md"
- Selecione arquivo do seu computador
- Edite se necessário
- Salve
Caso 4: Compartilhar documentação com equipe
- Acesse a documentação do flowkit
- Clique "Exportar .md"
- Compartilhe o arquivo .md via email, Slack, etc.
- Ou compartilhe o link direto: /flowkits/{slug}/documentation
Perguntas Frequentes
A documentação é versionada junto com o Flowkit?
Sim. Quando você incrementa a versão do Flowkit (ex: v1.0.0 → v1.1.0), a documentação fica associada a essa versão.
Posso editar manualmente a documentação gerada?
Sim, totalmente. A IA gera uma base, mas você pode personalizar qualquer seção.
A documentação é visível para todos no workspace?
Sim. Qualquer usuário com acesso ao Flowkit pode visualizar a documentação. Apenas usuários com permissões de edição podem modificar.
O que acontece se eu deletar um flow usado na documentação?
A próxima vez que regenerar com IA, o flow deletado será removido automaticamente da documentação.
Posso usar HTML dentro da documentação Markdown?
Não recomendado. A IA sanitiza HTML por segurança. Use apenas Markdown padrão.
Solução de Problemas
A geração de documentação falhou
Causa: Dados incompletos ou inválidos no Flowkit
Solução:
- Verifique se o Flowkit tem pelo menos 1 fluxo
- Confirme que nome e slug estão preenchidos
- Tente novamente
Documentação está desatualizada
Causa: Flowkit foi editado após a última geração de documentação
Solução:
- Acesse a página de documentação
- Clique "Regenerar com AI"
- Salve a nova versão
Não consigo importar arquivo .md
Causa: Arquivo muito grande ou formato inválido
Solução:
- Limite: 50KB por arquivo
- Certifique-se que é um arquivo .md válido
- Tente copiar/colar o conteúdo diretamente no editor
Próximos Passos
Depois de documentar seu Flowkit:
- Ative o Flowkit no ambiente desejado
- Compartilhe a documentação com sua equipe
- Mantenha atualizada sempre que fizer mudanças
- Use como referência para troubleshooting
Leia também:
- Criando Flowkits
- Versionamento de Flowkits
- Parâmetros de Flowkits
Precisa de ajuda? Entre em contato: [email protected]