Documentação e ADRs - Archyl Docs

Crie e gerencie documentação de arquitetura e Registros de Decisão de Arquitetura no Archyl

Documentação e ADRs

O Archyl oferece recursos poderosos de documentação que permitem criar documentação rica e vinculada, junto com seus diagramas de arquitetura. Mantenha seu conhecimento arquitetural organizado e conectado.

Criando Documentação

Documentação Manual

Para criar documentação manualmente:

  1. Vá para a aba Docs no seu projeto
  2. Clique em Novo Doc
  3. Insira um título e escreva seu conteúdo em Markdown
  4. Adicione tags para organização
  5. Clique em Salvar

A documentação suporta a sintaxe completa do Markdown incluindo:

  • Títulos e formatação
  • Blocos de código com destaque de sintaxe
  • Tabelas e listas
  • Imagens e links

Importando do Git

Você pode importar documentação existente do seu repositório Git:

  1. Vá para Configurações do Projeto > Descoberta de Documentação
  2. Configure sua conexão com o repositório
  3. Clique em Descobrir Docs
  4. Revise e aprove a documentação descoberta

Isso é perfeito para importar arquivos README existentes, especificações técnicas ou conteúdo de wiki.

Vinculando a Elementos de Arquitetura

A documentação se torna mais poderosa quando vinculada à sua arquitetura:

Criando Vínculos

  1. Abra uma página de documentação
  2. Clique em Vincular a Elemento
  3. Pesquise ou navegue pelo elemento de arquitetura
  4. Selecione o(s) elemento(s) para vincular
  5. Clique em Concluído

Visualizando Documentação Vinculada

Ao visualizar um elemento no diagrama, a documentação vinculada aparece no painel de detalhes. Isso fornece contexto instantâneo sem sair da visualização do diagrama.

Casos de Uso para Vinculação

  • Vincular documentação de API a containers de Serviço
  • Vincular guias de configuração a componentes de infraestrutura
  • Vincular especificações de design a contextos de sistema
  • Vincular comentários de código a elementos de Código

Registros de Decisão de Arquitetura (ADRs)

ADRs documentam decisões arquiteturais importantes com seu contexto e consequências.

O que é um ADR?

Um Registro de Decisão de Arquitetura captura:

Campo Descrição
Título O que foi decidido
Status Proposto, Aceito, Descontinuado ou Substituído
Contexto Por que essa decisão foi necessária
Decisão O que foi decidido
Consequências Impacto da decisão

Criando um ADR

  1. Vá para a aba Decisões no seu projeto
  2. Clique em Novo ADR
  3. Preencha os campos do ADR
  4. Vincule a elementos de arquitetura relevantes
  5. Clique em Salvar

Fluxo de Trabalho do ADR

ADRs seguem um ciclo de vida:

  1. Proposto: Rascunho inicial, em discussão
  2. Aceito: Decisão tomada e aprovada
  3. Descontinuado: Não mais relevante, mas mantido para histórico
  4. Substituído: Substituído por uma decisão mais recente

Descoberta de ADRs

Assim como a documentação, ADRs podem ser descobertos do seu repositório:

  1. Vá para Configurações do Projeto > Descoberta de ADRs
  2. Configure o caminho dos seus ADRs (ex.: docs/adr/)
  3. Clique em Descobrir ADRs
  4. Revise e aprove os registros descobertos

Boas Práticas

Mantenha a Documentação Atualizada

  • Atualize os docs quando a arquitetura mudar
  • Revise a documentação durante as retrospectivas de sprint
  • Use ADRs para decisões significativas

Vincule Tudo

  • Todo sistema deve ter um documento de descrição
  • Vincule ADRs aos componentes afetados
  • Faça referência cruzada de documentação relacionada

Use Tags de Forma Eficaz

  • Tageie por domínio (auth, pagamentos, etc.)
  • Tageie por tipo (api, guia, especificação)
  • Tageie por status (rascunho, revisão, final)

Diretrizes para ADRs

  • Crie ADRs para decisões significativas
  • Inclua alternativas consideradas
  • Documente os trade-offs
  • Vincule a PRs de implementação quando possível

Configurações de Descoberta de Documentação

Configure como a documentação é descoberta:

Padrões de Caminho

Especifique quais caminhos escanear:

docs/
wiki/
README.md
*.md

Padrões de Exclusão

Pule certos arquivos:

node_modules/
vendor/
CHANGELOG.md

Próximos Passos