Pular para o conteúdo principal

Processo de Documentação

Este documento define o processo e as diretrizes para documentação de código e funcionalidades no projeto.

1. Estrutura Mínima da Documentação​

Padrão por Componente​

A documentação de cada componente deve incluir:

  • Descrição: Explicação clara do propósito e comportamento do componente
  • Props: Lista completa de propriedades aceitas, seus tipos e valores padrão
  • Exemplos: Casos de uso práticos mostrando como utilizar o componente

Padrão por Funcionalidade/Módulo​

Para documentação de funcionalidades e módulos:

  • Fluxo: Descrição do fluxo de execução da funcionalidade
  • Telas: Screenshots ou descrições das interfaces envolvidas
  • Integrações: APIs, serviços externos ou outros módulos relacionados

Padrão para Boas Práticas de Front-end​

Documentação de convenções e padrões:

  • Nomenclatura: Convenções para nomes de variáveis, funções e arquivos
  • Separação de arquivos: Estrutura e organização do código
  • Performance: Diretrizes para otimização e melhores práticas

2. Responsabilidades​

Desenvolvedores​

  • Atualização obrigatória: Cada desenvolvedor deve atualizar a documentação ao criar ou modificar componentes/funcionalidades
  • Componentes reutilizáveis: Todo componente que será utilizado em mais de um lugar deve ser documentado
  • Regras de negócio: Customizações específicas de clientes devem ser documentadas
  • Novas funcionalidades: Features como Imposto, Cálculo de preço, Cálculo de frete, etc. devem ser documentadas

Revisão de PR​

  • Revisão obrigatória: A documentação deve ser revisada junto com o código no PR
  • Responsável: O mesmo revisor que aprova o PR do projeto deve aprovar o PR da documentação

3. Processo de Atualização​

Fluxo de Trabalho​

  1. Criar PR no repositório de documentação:
  2. Preencher template do PR:
    • Especificar o projeto que está sendo alterado
    • Indicar se houve alteração ou criação de nova documentação
  3. Vincular PRs:
    • Adicionar no PR do projeto o link do PR da documentação
  4. Aprovação sincronizada:
    • Quando o PR do projeto for aprovado, o PR da documentação também deve ser aprovado
    • O mesmo responsável deve aprovar ambos os PRs

4. Utilização de IA para Documentação​

Ferramentas Recomendadas​

  • GitHub Copilot: Para geração automática de documentação
  • ChatGPT: Para criação de conteúdo explicativo
  • Claude: Para análise e estruturação de documentação
  • GitChanges: Para identificação facilitada de mudanças no código
  • Gemini: Para geração automática de documentação
  • Cursor: Para geração automática de documentação

Processo com IA​

  1. Geração inicial: Utilizar IA para criar documentação base e acelerar o processo
  2. Revisão humana: Sempre revisar o conteúdo gerado para garantir precisão
  3. Validação: Confirmar que a documentação está alinhada com o código real

5. Boas Práticas​

Qualidade do Conteúdo​

  • Linguagem clara: Usar linguagem simples e direta
  • Exemplos práticos: Incluir exemplos de código funcionais
  • Contexto visual: Adicionar prints de tela quando relevante

Recursos Visuais​

  • Screenshots: Para documentação de telas e fluxos
  • Storybook interativo: Para componentes visuais
  • Diagramas: Para fluxos complexos quando necessário

Manutenção​

  • Atualização contínua: Manter documentação sempre sincronizada com o código
  • Versionamento: Documentar mudanças significativas entre versões
  • Feedback: Coletar e incorporar feedback da equipe para melhorar a documentação

Última atualização: 18 de setembro de 2025