6 min leitura • Guide 644 of 877
Melhores Práticas de Documentação
Uma boa documentação acelera a integração, reduz silos de conhecimento e previne perguntas repetidas. Os recursos de documentação do GitScrum ajudam as equipes a manter documentação viva ao lado do trabalho de desenvolvimento, garantindo que os docs permaneçam atuais e acessíveis.
Estratégia de Documentação
O Que Documentar
PRIORIDADES DE DOCUMENTAÇÃO:
┌─────────────────────────────────────────────────────────────┐
│ DEVE DOCUMENTAR: │
├─────────────────────────────────────────────────────────────┤
│ ✓ Instruções de início / Configuração │
│ ✓ Visão geral da arquitetura │
│ ✓ Documentação de API │
│ ✓ Opções de configuração │
│ ✓ Procedimentos de deployment │
│ ✓ Runbooks de incidentes │
│ │
│ DEVE CONSIDERAR DOCUMENTAR: │
├─────────────────────────────────────────────────────────────┤
│ ○ Registros de decisões arquiteturais (ADRs) │
│ ○ Etapas comuns de solução de problemas │
│ ○ Processos e acordos da equipe │
│ ○ Checklist de integração │
│ │
│ CONSIDERE NÃO DOCUMENTAR: │
├─────────────────────────────────────────────────────────────┤
│ ✗ Código óbvio (auto-documentado) │
│ ✗ Soluções temporárias (use comentários) │
│ ✗ Notas de reuniões (a menos que decisões) │
└─────────────────────────────────────────────────────────────┘
Tipos de Documentação
ESTRUTURA DE DOCUMENTAÇÃO:
┌─────────────────────────────────────────────────────────────┐
│ TIPO │ PÚBLICO │ PROPÓSITO │
├───────────────┼──────────────┼───────────────────────────────┤
│ README │ Novos devs │ Início rápido, visão geral │
│ Docs de API │ Consumidores │ Como usar o serviço │
│ Arquitetura │ Equipe │ Como o sistema funciona │
│ ADRs │ Equipe/Futuro│ Por que decisões foram tomadas │
│ Runbooks │ Ops/On-call │ Como responder a problemas │
│ Tutoriais │ Novos devs │ Aprendendo o codebase │
│ Referência │ Todos devs │ Detalhes técnicos completos │
└───────────────────────────────────────────────────────────────┘
Escrevendo Docs Eficazes
Template de README
ESTRUTURA PADRÃO DE README:
┌─────────────────────────────────────────────────────────────┐
│ # Nome do Projeto │
│ │
│ Descrição de uma linha do que isso faz. │
│ │
│ ## Início Rápido │
│ ```bash │
│ npm install && npm start │
│ ``` │
│ │
│ ## Pré-requisitos │
│ - Node.js 18+ │
│ - PostgreSQL 14+ │
│ │
│ ## Instalação │
│ Instruções passo-a-passo de configuração │
│ │
│ ## Configuração │
│ Variáveis de ambiente e opções │
│ │
│ ## Desenvolvimento │
│ Como executar localmente, testes, etc. │
│ │
│ ## Contribuição │
│ Como submeter mudanças │
│ │
│ ## Licença │
└─────────────────────────────────────────────────────────────┘
Registros de Decisões Arquiteturais
TEMPLATE DE ADR:
┌─────────────────────────────────────────────────────────────┐
│ # ADR-001: Usar PostgreSQL para banco de dados primário │
│ │
│ ## Status │
│ Aceito │
│ │
│ ## Contexto │
│ Precisamos de um banco de dados para dados de usuário. │
│ Requisitos: │
│ - Conformidade ACID │
│ - Suporte a JSON │
│ - Familiaridade da equipe │
│ │
│ ## Decisão │
│ Usaremos PostgreSQL 14. │
│ │
│ ## Consequências │
│ - Equipe já conhece PostgreSQL │
│ - Bom ecossistema de ferramentas │
│ - Precisaremos gerenciar upgrades │
│ │
│ ## Alternativas Consideradas │
│ - MySQL: Menos suporte a JSON │
│ - MongoDB: Equipe não familiar │
│ │
│ Data: 2024-01-15 │
│ Autores: @jane, @john │
└─────────────────────────────────────────────────────────────┘
Mantendo Docs Atuais
Docs na Definição de Pronto
DEFINIÇÃO DE PRONTO DE RECURSO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ CÓDIGO COMPLETO: │
│ □ Implementação feita │
│ □ Testes escritos │
│ □ Código revisado │
│ │
│ DOCUMENTAÇÃO COMPLETA: │
│ □ Docs de API atualizados (se API mudou) │
│ □ README atualizado (se configuração mudou) │
│ □ Docs de arquitetura atualizados (se significativo) │
│ □ Runbooks atualizados (se operações afetadas) │
│ │
│ PRONTO PARA DEPLOY: │
│ □ Entrada de changelog adicionada │
│ □ Notas de release redigidas │
└─────────────────────────────────────────────────────────────┘
Ciclo de Revisão de Documentação
REVISÃO TRIMESTRAL DE DOCS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ CADA TRIMESTRE: │
│ │
│ 1. AUDITORIA (1 hora) │
│ Listar toda documentação │
│ Notar datas de última atualização │
│ Sinalizar conteúdo obsoleto (> 6 meses) │
│ │
│ 2. PRIORIZAR (30 min) │
│ Docs críticos que estão obsoletos │
│ Frequentemente acessados mas desatualizados │
│ Novas áreas precisando de docs │
│ │
│ 3. CRIAR TAREFAS (30 min) │
│ Adicionar tarefas de atualização de docs ao GitScrum │
│ Atribuir proprietários │
│ Agendar em sprints próximos │
│ │
│ 4. ACOMPANHAR │
│ Usar rótulo de documentação │
│ Incluir no planejamento de sprint │
└─────────────────────────────────────────────────────────────┘
Integração com GitScrum
NoteVault para Wiki da Equipe
ORGANIZAÇÃO DO NOTEVAULT:
┌─────────────────────────────────────────────────────────────┐
│ 📁 Wiki da Equipe │
├─────────────────────────────────────────────────────────────┤
│ ├── 📄 Iniciando │
│ │ └── Integração de novo desenvolvedor │
│ ├── 📁 Arquitetura │
│ │ ├── Visão Geral do Sistema │
│ │ ├── Design de API │
│ │ └── Schema do Banco de Dados │
│ ├── 📁 Processos │
│ │ ├── Diretrizes de Code Review │
│ │ ├── Processo de Release │
│ │ └── Procedimentos On-Call │
│ └── 📁 ADRs │
│ ├── ADR-001: Escolha do Banco de Dados │
│ ├── ADR-002: Estratégia de Auth │
│ └── ADR-003: Versionamento de API │
└─────────────────────────────────────────────────────────────┘