Bem-vindo ao Guia Completo de Desenvolvedores da Plataforma de Documentação Centralizada de Automações. Este documento é o seu recurso primordial para entender, interagir, contribuir e manter a documentação essencial de todos os nossos fluxos automatizados.
1.1. Visão Geral da Plataforma de Documentação Centralizada
A Plataforma de Documentação Centralizada é uma iniciativa estratégica fundamental para garantir a governança, a estabilidade e a transparência de nossas automações. Desenvolvida para combater problemas como a quebra de automações, a falta de documentação e a ausência de visibilidade para stakeholders, ela se estabelece como a única fonte de verdade para todo o conhecimento técnico relacionado aos nossos fluxos de trabalho no Hyperflow, N8N, HubSpot e outras integrações.
Seu principal objetivo é:
Prevenir Quebras: Fornecendo um entendimento profundo das dependências e comportamentos dos fluxos.
Acelerar o Onboarding e Manutenção: Centralizando o conhecimento técnico e eliminando o “bus factor”.
Garantir Transparência: Permite que desenvolvedores e stakeholders compreendam o funcionamento das automações.
Padronizar a Documentação: Oferecendo uma estrutura consistente para cada fluxo, nó, variável e integração.
Este guia é dedicado aos desenvolvedores, fornecendo as ferramentas e o conhecimento necessário para que cada contribuição seja eficaz e alinhada com os objetivos da plataforma.
2. Como o Sistema de Documentação Funciona: A Stack Tecnológica
Nossa Plataforma de Documentação Centralizada é construída sobre uma stack tecnológica leve e eficiente, projetada para flexibilidade, fácil manutenção e publicação rápida. Entender cada componente e como eles se interligam é crucial para o seu trabalho.
2.1. Componentes Principais:
Markdown (.md): O Conteúdo da Documentação
Todo o coração da nossa documentação reside em arquivos de texto simples, formatados usando a linguagem Markdown. É uma sintaxe leve e fácil de aprender, que permite estruturar texto, adicionar cabeçalhos, listas, links, imagens e blocos de código de forma consistente.
Seu Editor Preferido (Obsidian Recomendado para Experiência)
Você pode usar qualquer editor de texto que suporte arquivos Markdown para criar e editar a documentação. No entanto, o Obsidian é fortemente recomendado devido à sua capacidade de vincular notas, agilizar a criação com templates, visualizar gráficos de relacionamento e sua vasta gama de plugins que otimizam a experiência de documentação e navegação local.
Quartz: O Gerador de Site Estático
Quartz é uma biblioteca JavaScript que atua como nosso Static Site Generator (SSG). Ele lê todos os seus arquivos Markdown (.md), processa-os e os transforma em um conjunto de arquivos web estáticos (HTML, CSS e JavaScript). Isso significa que a documentação, uma vez compilada, é um website leve e robusto que não requer um banco de dados complexo ou um servidor dinâmico para rodar.
Git: O Sistema de Controle de Versionamento
Todas as alterações nos arquivos Markdown e nos arquivos estáticos gerados são gerenciadas pelo Git. O Git é essencial para rastrear o histórico das mudanças, colaborar com a equipe e reverter para versões anteriores, se necessário. Ele garante que tenhamos total rastreabilidade sobre a evolução da documentação.
Vercel: A Plataforma de Deploy
Após as alterações serem enviadas para o repositório Git, o Vercel entra em ação. Ele é configurado para monitorar nosso repositório e, automaticamente, pega os arquivos gerados pelo Quartz, constrói o site e o publica online. Isso garante que a versão mais recente da documentação esteja sempre acessível através de uma URL pública.
2.2. Fluxo de Trabalho Simplificado:
Criar/Editar .md: Você escreve/edita arquivos Markdown em seu editor (Obsidian, Cursor etc.).
Compilar (Local): Você executa npx quartz build para gerar uma versão local do site estático.
Visualizar (Local): O comando npx quartz build --serve permite visualizar as alterações em seu navegador antes de publicar.
Versionar: Você usa git para commitar suas mudanças e enviá-las para o repositório central.
Publicar (Automático): O Vercel detecta as mudanças no Git e implanta automaticamente a nova versão da documentação online.
3. Estrutura Geral do Repositório de Documentação
Nosso repositório é organizado de forma lógica para facilitar a localização e a contribuição de documentos. Entender esta estrutura é crucial para a correta organização dos seus arquivos Markdown.
.
├── flows/
│ ├── [plataforma]/
│ │ └── [nome-do-fluxo]/
│ │ ├── index.md # Documento geral do fluxo (gerado por IA)
│ │ ├── [id-do-no]-chat-saudacao.md # Documentação de um nó (ex: 8a-chat-va-pro-app.md)
│ │ └── [id-do-no]-condicao-verificacao.md # Outro nó
│ └── ...
├── guides/
│ ├── templates/
│ │ └── node.md # Template para documentar nós individuais
│ │ └── template-doc-fluxo.md # Template para a IA gerar o doc. geral do fluxo
│ └── guia-desenvolvedores-completo.md # Este guia
│ └── node-types-reference.md # Referência de tipos de nó
│ └── ...
├── narratives/
│ └── Iniciativa de Governança de Automações.md # Contexto e decisões estratégicas
│ └── ...
└── index.md # Quickstart (landing page do sistema)
Componentes da Estrutura:
/flows:
Esta é a pasta principal onde toda a documentação das automações reside.
Organização por Plataforma: Dentro de flows/, subpastas são criadas para cada plataforma de automação (ex: hyperflow, n8n, hubspot), permitindo uma categorização clara.
Pastas de Fluxo Individual: Para cada fluxo de automação, há uma pasta dedicada (ex: flows/hyperflow/transbordo-app/).
index.md (Documento Geral do Fluxo): Dentro de cada pasta de fluxo (ex: flows/hyperflow/transbordo-app/), o arquivo index.md é o documento principal que descreve o fluxo de forma abrangente. Este arquivo é gerado pela IA a partir das documentações dos nós individuais e segue a estrutura definida no template-doc-fluxo.md. O Quartz reconhece automaticamente index.md como a página de exibição principal para aquela pasta, criando uma navegação bidimensional (visão geral do fluxo e detalhes dos nós).
Documentação dos Nós Individuais ([id-do-no]-tipo-nome.md): Também dentro da pasta de cada fluxo, você encontrará (e criará) os arquivos Markdown para cada nó individual (os “documentos atômicos”). Estes são os resultados da documentação nó a nó usando o node.md.
Regras de Nomenclatura dos Nós: A nomenclatura é crucial para a legibilidade e para a IA. O padrão é [id-do-no]-[tipo-do-no]-[nome-descritivo-curto].md (ex: 8a-chat---va-pro-app.md). O id-do-no é especialmente importante para a IA interpretar a sequência e construir o diagrama Mermaid corretamente.
/guides:
Contém guias de uso, documentações de ferramentas e templates utilizados no processo de documentação.
/guides/templates: Armazena os templates Markdown (node.md para nós, template-doc-fluxo.md para a IA geral do fluxo) e a node-types-reference.md.
/narratives:
Contém documentos de contexto, justificativas, decisões estratégicas e históricas sobre a iniciativa de governança de automações e outros projetos.
index.md (Raiz):
A página inicial (landing page) do sistema de documentação online, que serve como um Quickstart e ponto de entrada para o usuário.
Esta estrutura permite:
Navegação Bidimensional: A partir da página index.md de um fluxo, o usuário pode rapidamente navegar para os detalhes de qualquer nó individual dentro da mesma pasta.
Contexto Abrangente: Todos os arquivos relacionados a um fluxo estão agrupados.
Padronização: Facilita a localização e a compreensão dos padrões de organização.
4. Como Configurar o Ambiente de Desenvolvimento
Esta seção guiará você através da configuração inicial do seu ambiente local para criar e gerenciar a documentação das automações.
4.1. Pré-requisitos
Antes de começar, certifique-se de que você possui o seguinte instalado em sua máquina:
Node.js e npm/yarn: O Quartz é uma biblioteca JavaScript que requer um gerenciador de pacotes. Recomendamos a versão mais recente do Node, que inclui o npm. Você pode baixar em nodejs.org.
Verificação: Abra seu terminal ou prompt de comando e execute:
node -vnpm -v
Você deverá ver os números das versões instaladas.
Git: Essencial para versionar seu trabalho e interagir com o repositório central.
Verificação: No terminal, execute:
git --version
Um Editor de Texto/IDE:
Obsidian (Recomendado): Para uma experiência otimizada com plugins úteis na criação e organização de arquivos Markdown. Baixe em obsidian.md.
Alternativamente: Você pode usar qualquer editor de texto que suporte arquivos Markdown (.md).
4.2. Clonar o Repositório da Documentação
Todo o conteúdo da documentação de automações é armazenado em um repositório Git. Você precisa clonar este repositório para sua máquina.
Abra seu terminal.
Navegue até a pasta onde você deseja armazenar os arquivos de documentação.
Execute o seguinte comando, substituindo URL_DO_SEU_REPOSITORIO_GIT pela URL real do seu repositório:
Após a clonagem, navegue para a pasta recém-criada:
cd nome-do-seu-repositorio
4.3. Instalar o Quartz
O Quartz é a ferramenta que transforma seus arquivos Markdown em páginas web estáticas. Você o instalará como uma dependência de desenvolvimento do projeto.
No terminal, dentro da pasta raiz do seu repositório clonado, execute o seguinte comando para instalar as dependências do projeto, incluindo o Quartz e suas dependências:
npm install
Alternativamente, se você prefere usar o Yarn:
yarn install
Este comando irá baixar e instalar todas as bibliotecas listadas no arquivo package.json do repositório.
4.4. Configurar o Obsidian (Opcional, mas recomendado)
Se você estiver usando o Obsidian, siga estes passos para integrar sua documentação:
Abra o Obsidian.
Vá em File > Open folder as vault... (ou Arquivo > Abrir pasta como cofre...).
Selecione a pasta content Git que você clonou na etapa 4.2.
O Obsidian reconhecerá os arquivos .md e você poderá começar a editar.
4.5. Começar a Trabalhar (Desenvolvimento Local)
(validar se funcionalidade de navegação funciona dessa forma)
Agora seu ambiente está pronto! Para iniciar um servidor de desenvolvimento local e visualizar suas alterações em tempo real:
No terminal, dentro da pasta raiz do repositório, execute:
npx quartz build --serve
Este comando irá:
Compilar seus arquivos Markdown (.md) usando o Quartz.
Iniciar um servidor web local.
Abra seu navegador e acesse o endereço fornecido pelo terminal (geralmente http://localhost:8080 ou similar). Você verá a versão local do seu site de documentação.
Resumo do Fluxo de Trabalho em Desenvolvimento
Edite arquivos .md no Obsidian (ou outro editor).
Execute npx quartz build --serve no terminal para ver as alterações no localhost.
Quando terminar uma edição ou adicionar novo conteúdo, use git add ., git commit -m "Mensagem Descritiva" e git push para enviar suas contribuições.
5. Como Contribuir com a Documentação
A contribuição para a Plataforma de Documentação Centralizada é um processo estruturado, projetado para garantir que todo o conhecimento sobre nossas automações seja capturado de forma consistente, detalhada e eficiente. Esteja você documentando um novo fluxo ou atualizando um existente, seguir este guia garantirá que suas contribuições sejam valiosas e alinhadas aos nossos padrões.
5.1. Visão Geral do Processo de Documentação de Fluxos
O ciclo de vida da documentação de um fluxo é dividido em três fases principais para garantir granularidade, padronização e automação na geração do documento final:
Documentação Atômica dos Nós:
O que é: Para cada elemento operacional (nó) do seu fluxo de automação (seja ele um nó de Condição, Chat, HTTP Request, Jump, etc.), você criará uma documentação individual e focada.
Ferramenta: Esta etapa é realizada no Obsidian, utilizando o template interativo guides/templates/node.md, que guia a coleta de dados específicos para cada tipo de nó.
Output: Múltiplos arquivos Markdown (.md), cada um representando um nó distinto do fluxo. Estes são os “documentos atômicos”.
Consolidação e Geração do Documento do Fluxo (AI-Powered):
O que é: Uma vez que todos os nós de um fluxo foram documentados individualmente, seus conteúdos são reunidos e processados por uma ferramenta de Inteligência Artificial.
Ferramenta: Você irá “alimentar” a IA com o conteúdo consolidado dos nós e o template mestre guides/template-doc-fluxo.md.
Função da IA: A IA interpreta as informações dos nós, organiza-as e as estrutura no formato do template-doc-fluxo.md, criando um documento Markdown coeso e completo para o fluxo inteiro.
Output: Um único arquivo Markdown (.md) que descreve o fluxo completo de automação, pronto para ser publicado.
Publicação e Versionamento:
O que é: O documento Markdown final do fluxo é então transformado em uma página web estática e publicado em nosso portal de documentação. Note que os nós individuais também são publicados, criando uma rica estrutura de navegação bidimensional.
Ferramenta: Esta etapa envolve comandos de linha (npx quartz build, git add, git commit, git push) que convertem o Markdown e o enviam para o repositório Git, o qual está integrado ao Vercel para deploy automático.
Output: A documentação do seu fluxo (incluindo a visão geral e os detalhes de cada nó) estará disponível e pesquisável em nossa plataforma online.
Este processo garante que cada detalhe seja capturado na origem (nível do nó) e que a apresentação final seja padronizada e de alta qualidade (nível do fluxo, gerada por IA).
5.2. Documentando Nós Individuais (Atomic Docs)
A documentação começa no nível mais granular: o nó. Cada nó de seu fluxo deve ser documentado separadamente para garantir a clareza e a reusabilidade das informações. Apesar de focar na granularidade, o processo é projetado para ser simples e ágil, com o auxílio de templates interativos.
Você já notou que todos os nós individuais são publicados na documentação. Onde cada pasta representa um fluxo, dentro da pasta do fluxo temos os nós individuais documentados seguindo as regras de nomenclatura. Além das notas dos nós individuais, na mesma pasta fica o documento geral daquele fluxo como index.md, que o Quartz entende como página de exibição. A ideia é que com essa documentação bidimensional, o usuário possa navegar entre uma visão geral do fluxo e os detalhes de cada fluxo.
5.2.1. O Template node.md no Obsidian
O coração da documentação atômica é o template guides/templates/node.md, projetado para ser usado no Obsidian. Este template é interativo e irá guiá-lo na criação de cada nota de nó.
Como Utilizar (Obsidian + Templater Plugin):
Crie uma Nova Nota com o Template:
No Obsidian, certifique-se de ter o plugin Templater habilitado e configurado para usar guides/templates/node.md como um de seus templates.
Use o atalho configurado para o Templater (ou o comando Templater: Create new note from template) e selecione node.md.
Responda aos Prompts Interativos:
O template iniciará uma sequência de perguntas. A primeira e mais crucial é: “Selecione o tipo do nó”. Sua escolha aqui (ex: Condition, Chat, Jump, HTTP Request) determina os campos específicos que serão solicitados a seguir.
Preencha as informações gerais do nó (nome do workflow, plataforma, tags, descrição, contexto, nós anterior/próximo).
Preencha os campos específicos que aparecerem, conforme o tipo de nó selecionado. Seja conciso e preciso nas respostas.
Vincule Notas Relacionadas (se houver):
O template também oferecerá a opção de selecionar e vincular outras notas (.md de outros nós) que já existam na pasta, criando referências bidirecionais importantes.
Salve o Arquivo:
Após preencher todos os prompts, o Obsidian gerará o arquivo Markdown com a estrutura preenchida.
Salve este arquivo .md na pasta do fluxo correspondente (ex: flows/hyperflow/transbordo-app/), seguindo a regra de nomenclatura.
Exemplo de um Documento Atômico de Nó (Simplificado):
Para ilustrar como é simples e direto documentar um nó, veja este exemplo de um nó de Chat (conforme o arquivo flows/hyperflow/transbordo-app/8a-chat---va-pro-app.md):
---id: 8a-chat---va-pro-appflow: transbordo-apptype: Chattags: - workflow - automation - hyperflowrelated: []revision_state: 1762968868tracked: false---## Configuração do Chat**Conteúdo**: `{{user.name.split(" ")[0]}}`, sua proposta te espera! 🚀 Contrate e tire suas dúvidas direto no app! 😉📱**Rodapé**: Clique no botão abaixo e vá para o app Konsi ⬇️**Botões**: Acessar app Konsi ([url](https://konsi.go.link/?adj_t=za831l6&adj_deep_link=konsiadjust%3A%2F%2F%2Ftabview&adj_campaign=whatsapp&adj_adgroup=buer_disparo_cs_v3&adj_creative=low_ticket&adj_fallback=https%3A%2F%2Fwww.konsi.com.br%2Fdownload-app&adj_redirect_macos=https%3A%2F%2Fwww.konsi.com.br%2Fdownload-app))**Opções**:- Aguardar resposta do usuário: true- Tratar mensagem fora de contexto: false- Continuar automaticamente: false## SaídasN/A (Interação com usuário via chat)## Descrição adicionalEste nó envia uma mensagem de chatbot para o usuário, incentivando-o a baixar e usar o aplicativo Konsi para acessar sua proposta de crédito.## Relações← Recebe de: [[7-start-inactivity---23-horas]] → Envia para: [[9a-rotulo---low-touch-respondeu]]
Note como as perguntas do template geram campos diretos, e os links de “Relações” são automaticamente preenchidos pelo Templater, facilitando a navegação.
5.2.2. Guia de Tipos de Nó e seus Campos
Para uma referência detalhada sobre cada tipo de nó compatível com o node.md, seus prompts específicos (campos) e a estrutura de saída Markdown esperada, consulte a página dedicada:
É fundamental consultar esta referência para entender a profundidade e o formato de cada campo antes de preencher o template.
5.2.3. Regras de Nomenclatura para Notas de Nó
A nomenclatura dos arquivos de nó é vital para a organização, legibilidade e, crucialmente, para o correto funcionamento da IA na construção do diagrama Mermaid e na interpretação da sequência de execução.
[id-do-no]: Um identificador único e sequencial para o nó dentro do fluxo (ex: 1, 2a, 3b, 7A). É comum usar dígitos e letras para branches. Para fluxos complexos, utilizamos o conceito de Lanes (veja seção 5.2.5). Este ID é fundamental para a IA inferir a ordem e as conexões do fluxo.
[tipo-do-no]: O tipo de nó (ex: chat, condition, jump, http-request). Use slugs (tudo minúsculo, hifens).
[nome-descritivo-curto]: Uma breve descrição do que o nó faz, também em slugs (ex: va-pro-app, verifica-status).
Exemplo:8a-chat---va-pro-app.md
8a: ID do nó na sequência do fluxo.
chat: Tipo do nó.
va-pro-app: Descrição concisa.
Importância:
Mermaid Diagrams: A IA ou o sistema de visualização pode usar esses IDs para construir automaticamente o fluxograma, facilitando a visualização.
Navegação e Leitura: Ajuda a identificar rapidamente a função de um nó em sua pasta.
Consistência: Garante um padrão em todo o repositório.
5.2.4. Boas Práticas ao Documentar Nós
Conectividade Bidimensional (Crítico): Certifique-se de que os campos “Relações” (← Recebe de e → Envia para) estejam sempre preenchidos em cada nota atômica. Isso garante que a navegação local (pular entre nós vizinhos) e global (index) funcione sem interrupções.
Contextualização de Saídas: Para nós que encerram um processo ou ramificação (ex: RabbitMQ Action, HTTP Response, End Flow), não se limite à configuração técnica. Descreva o impacto final ou o “efeito colateral” no negócio (ex: “Dispara mensagem de recuperação para o cliente”).
Sincronização Mermaid/ID: Os IDs usados no diagrama Mermaid do index.md devem ser idênticos aos id definidos no frontmatter dos arquivos de nó.
Links Robustos e Aliases: Ao referenciar nós em tabelas ou textos, prefira o caminho relativo completo com aliases para evitar quebras por caminhos ambíguos: [[flows/plataforma/fluxo/id-no.md|Nó X]].
Dados Reais, se Possível: Utilize exemplos de dados reais ou simulados que o nó processa para tornar a documentação mais concreta.
Links para Referências: Se um nó interage com uma API ou serviço complexo, adicione uma observação com um link para a documentação externa relevante.
5.2.5. Estruturas de Ramificação Complexa (Lanes)
Para fluxos que possuem ramificações profundas e paralelas (ex: roteamento por time, múltiplos canais de atendimento), adotamos a convenção de Lanes (Faixas).
Conceito: Uma “Lane” agrupa visualmente e logicamente uma sequência de nós que pertencem a um mesmo contexto após uma grande divisão.
Estrutura:[Sequência]-[Lane][SubLane]-[Descrição]
Elemento
Descrição
Exemplo
Sequência
Número sequencial global do passo.
7
Lane
Letra Maiúscula (A, B, C…) identificando a faixa.
A
SubLane
(Opcional) Dígito ou letra para subdivisões internas.
1
Exemplo Prático:
Imagine um fluxo que no passo 6 se divide para 3 times:
Passo 6 (Hub):6-conditional---roteamento.md
Lane A (Time Vendas):
7A-conditional---vendas-check.md
8A1-action---vendas-aprovado.md
8A2-action---vendas-reprovado.md
Lane B (Time Suporte):
7B-action---suporte-ticket.md
8B-action---suporte-email.md
Lane C (Time Financeiro):
7C-action---fin-validacao.md
Isso permite que a Lane B cresça (9B, 10B…) sem interferir na numeração da Lane A.
5.2.6. Diretrizes Premium para o Documento Geral (index.md)
Para que a documentação atinja o nível “Plataforma Centralizada”, o index.md deve ir além de um sumário técnico:
Fases Lógicas (Narrativa Técnica): Em vez de uma lista contínua de nós, agrupe o fluxo em fases lógicas (ex: Fase 1: Coleta e Identificação, Fase 2: Validação de Regras, Fase 3: Execução/Disparo). Isso transforma o código em um processo de negócio compreensível.
Visão de Valor: No campo “Objetivo”, conecte a funcionalidade técnica à dor de negócio (ex: “Reduzir o churn de conversão em 15%”).
Mapeamento de Dependências Externas: Garanta que Jumps e Chamadas de API estejam linkados tanto no Detailed Flow quanto na seção de External Dependencies.
5.3. Boas Práticas para Diagramas Mermaid no Quartz
Durante a implementação dos diagramas, é crucial observar a compatibilidade entre o Obsidian e o Quartz. O Quartz utiliza a versão v11.4.0 do Mermaid, que possui um parsing mais rígido que as versões v9/v10 comumente usadas no Obsidian.
5.3.1. Incompatibilidades Comuns e Soluções
**Comentários Internos (“ de dentro do bloco do diagrama.
Texto Solto:
Problema: Texto solto (ex: Lane B: Buy Intention) quebra o parser.
Solução: Todo texto deve estar associado a um nó ou aresta, ou devidamente encapsulado em um subgrafo.
Labels de Arestas:
Problema: Labels sem aspas podem causar erros de sintaxe dependendo dos caracteres usados.
Solução: Sempre coloque aspas em labels de arestas.
Errado:-- Texto -->
Correto:-- "Texto" -->
Nós Especiais:
Problema: Sintaxe simplificada para nós especiais pode falhar.
Solução: Use colchetes ou parênteses duplos com aspas se necessário, ou simplifique.
Preferível:(("Fim")) ou [Fim] em vez de construções complexas não suportadas.
5.3.2. Recomendação de Fluxo de Trabalho
Verifique a Versão: Tenha em mente que o ambiente de publicação (Quartz) é a autoridade final.
Padrão v11+: Escreva seus diagramas já pensando nas restrições da versão v11+.
Teste Mínimo: Antes de publicar um fluxo complexo, teste um diagrama mínimo no Quartz (npx quartz build --serve) para validar a sintaxe.
5.3. Boas Práticas para Diagramas Mermaid no Quartz
Durante a implementação dos diagramas, é crucial observar a compatibilidade entre o Obsidian e o Quartz. O Quartz utiliza a versão v11.4.0 do Mermaid, que possui um parsing mais rígido que as versões v9/v10 comumente usadas no Obsidian.
5.3.1. Incompatibilidades Comuns e Soluções
Comentários Internos (%%):
O Quartz não tolera comentários internos dentro do bloco graph TD.
Texto Solto:
Texto solto (ex: Lane B: Buy Intention) quebra o parser. Todo texto deve estar associado a um nó ou aresta, ou devidamente encapsulado em um subgrafo.
Labels de Arestas:
Labels sem aspas podem causar erros de sintaxe dependendo dos caracteres usados. Sempre coloque aspas em labels de arestas.
Errado:-- Texto -->
Correto:-- "Texto" -->
Nós Especiais:
Sintaxe simplificada para nós especiais pode falhar. Use colchetes ou parênteses duplos com aspas se necessário, ou simplifique.
Preferível:(("Fim")) ou [Fim] em vez de construções complexas não suportadas.
5.3.2. Recomendação de Fluxo de Trabalho
Verifique a Versão: Tenha em mente que o ambiente de publicação (Quartz) é a autoridade final.
Padrão v11+: Escreva seus diagramas já pensando nas restrições da versão v11+.
Teste Mínimo: Antes de publicar um fluxo complexo, teste um diagrama mínimo no Quartz (npx quartz build --serve) para validar a sintaxe.
5.4. Modificando um Fluxo Existente
Esta seção será detalhada futuramente. Ela abordará os procedimentos para atualizar a documentação de nós individuais e re-gerar/validar o documento geral do fluxo após alterações.
6. Padrões e Regras de Documentação
Esta seção será detalhada futuramente. Ela incluirá diretrizes sobre a estrutura e formato padrão dos documentos, convenções de nomenclatura, nível de detalhe esperado, e como documentar decisões e narrativas.
7. Manutenção e Boas Práticas
Esta seção será detalhada futuramente. Ela cobrirá a rotina esperada para manter a documentação atualizada, como identificar e reportar documentação desatualizada, e a importância de revisões periódicas.
8. Recursos Adicionais
Esta seção será detalhada futuramente. Ela providenciará links úteis para a documentação do Quartz, Git, Markdown, além de informações de suporte e contato da equipe responsável pela governança da documentação.