Melhores Práticas Documentação | README ADR Wiki Docs
Documentação eficaz: README, docs de API, ADRs, runbooks. Inclua docs na Definição de Pronto. Revisão trimestral. GitScrum NoteVault para wiki equipe.
6 min de leitura
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 │
│ │
│ │
│ ## 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 │ └─────────────────────────────────────────────────────────────┘
``