8 min leitura • Guide 256 of 877
Melhores Práticas de Documentação de Equipe
Documentação é um ativo ou um passivo. Boas docs ajudam no onboarding, reduzem perguntas e preservam conhecimento. Docs ruins—desatualizadas, difíceis de encontrar ou incompletas—prejudicam ativamente ao fornecer informações erradas. A chave é documentar as coisas certas nos lugares certos com manutenção sustentável.
Tipos de Documentação
| Tipo | Propósito | Frequência de Atualização |
|---|---|---|
| Architecture Decision Records | Por que decisões foram tomadas | Quando decisões mudam |
| README | Como começar | Com mudanças importantes |
| Runbooks | Como lidar com incidentes | Após incidentes |
| Docs de API | Especificação de contrato | Com mudanças na API |
| Docs de processo | Como a equipe trabalha | Revisão trimestral |
O Que Documentar
Documentação de Alto Valor
PRIORIDADES DE DOCUMENTAÇÃO
════════════════════════════
DEVE TER:
─────────────────────────────────────
1. GUIA DE SETUP
"Como fazer isso rodar localmente"
├── Pré-requisitos
├── Clone e instalação
├── Setup de ambiente
├── Rodando localmente
├── Rodando testes
├── Problemas comuns
└── Guia da primeira tarefa
2. VISÃO GERAL DA ARQUITETURA
"Como este sistema funciona"
├── Diagrama de alto nível
├── Componentes e responsabilidades
├── Fluxo de dados
├── Tecnologias principais
└── Dependências externas
3. DECISÕES DE ARQUITETURA (ADRs)
"Por que escolhemos essa abordagem"
├── Contexto
├── Decisão
├── Consequências
└── Alternativas consideradas
4. PROCESSOS DA EQUIPE
"Como trabalhamos juntos"
├── Workflow de desenvolvimento
├── Processo de code review
├── Cerimônias de sprint
├── Rotação de plantão
└── Caminhos de escalação
5. RUNBOOKS
"Como lidar com problemas"
├── Processo de deploy
├── Procedimento de rollback
├── Incidentes comuns
└── Contatos de emergência
O Que NÃO Documentar
PULE ESSAS DOCS
═══════════════
NÃO DOCUMENTE:
─────────────────────────────────────
✗ Código óbvio
O código se explica sozinho.
Se não explica, melhore o código.
✗ Detalhes que mudam rapidamente
Vai estar desatualizado imediatamente.
Cria passivo, não ativo.
✗ Coisas que são melhores como comentários
Mantenha docs perto do código.
Comentários inline > doc separada.
✗ Duplicando docs oficiais
Link para docs externas ao invés.
Não copie-cole docs do React.
✗ Cada caso de borda
Documente padrões, não exceções.
Deixe desenvolvedores raciocinar.
REGRA PRÁTICA:
─────────────────────────────────────
Se vai estar errado em 2 semanas,
ou não documente ou automatize.
Se alguém perguntar a mesma coisa 3 vezes,
documente a resposta.
Localização da Documentação
Onde Docs Ficam
POSICIONAMENTO DE DOCUMENTAÇÃO
═══════════════════════════════
PERTO DO CÓDIGO:
─────────────────────────────────────
├── README.md: Visão geral do repo, setup
├── docs/: Docs específicas do projeto
│ ├── architecture.md
│ ├── deployment.md
│ └── api.md
├── Comentários inline: Contexto no código
└── Mensagens de commit: Por que mudanças foram feitas
NO SISTEMA DE GESTÃO DE PROJETOS (GitScrum):
─────────────────────────────────────
├── Processos de equipe
├── Checklists de sprint
├── Critérios de aceite
└── Contexto de tarefas
EM WIKI/CONFLUENCE:
─────────────────────────────────────
├── Documentação entre equipes
├── Guias de onboarding
├── Políticas da empresa
└── Docs de alto nível de produto
Princípios de Organização
ORGANIZAÇÃO DE DOCS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ PRINCÍPIOS: │
│ │
│ 1. DISCOVERABILITY (facilidade de encontrar) │
│ • Nomes claros e consistentes │
│ • Estrutura previsível │
│ • Search funciona │
│ • Links entre docs relacionadas │
│ │
│ 2. PROXIMIDADE AO USO │
│ • Docs de código perto do código │
│ • Runbooks perto de alertas │
│ • API docs geradas automaticamente │
│ │
│ 3. PROPRIEDADE CLARA │
│ • Cada doc tem um dono │
│ • Dono responsável por manter atualizada │
│ • Data de última revisão visível │
│ │
│ 4. SINGLE SOURCE OF TRUTH │
│ • Não duplique informação │
│ • Link ao invés de copiar │
│ • Uma fonte autoritativa por tópico │
└─────────────────────────────────────────────────────────────┘
Mantendo Docs Atualizadas
Estratégias de Manutenção
MANTENDO DOCUMENTAÇÃO VIVA:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ESTRATÉGIA 1: INTEGRAÇÃO NO WORKFLOW │
│ │
│ • Adicionar checklist de docs ao PR template │
│ • Atualizar docs como parte da definição de done │
│ • Revisores verificam se docs precisam atualização │
│ │
│ ESTRATÉGIA 2: DOCS-AS-CODE │
│ │
│ • Docs no mesmo repo que código │
│ • Mesmo processo de review │
│ • Versionadas junto com código │
│ │
│ ESTRATÉGIA 3: AUTOMAÇÃO │
│ │
│ • API docs geradas do código │
│ • Diagramas gerados automaticamente │
│ • Testes de links quebrados │
│ │
│ ESTRATÉGIA 4: REVISÃO PERIÓDICA │
│ │
│ • Revisão trimestral de docs importantes │
│ • Marcar docs com data de revisão │
│ • Arquivar docs obsoletas │
└─────────────────────────────────────────────────────────────┘
Indicadores de Qualidade
| Sinal | Docs Saudáveis | Docs Problemáticas |
|---|---|---|
| Uso | Equipe referencia frequentemente | Ninguém lê |
| Perguntas | Diminuíram | Mesmas perguntas repetidas |
| Atualização | Feitas regularmente | Última atualização há meses |
| Feedback | Positivo | "A doc está errada" |
| Onboarding | Novos membros acham útil | Precisam perguntar tudo |
Escrevendo Boas Docs
Estrutura Recomendada
TEMPLATE DE DOCUMENTO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ # Título │
│ │
│ > TL;DR: Uma frase resumindo o propósito │
│ │
│ ## Contexto │
│ Por que esta doc existe, quando usar │
│ │
│ ## Pré-requisitos │
│ O que você precisa saber/ter antes │
│ │
│ ## Passos / Conteúdo Principal │
│ O core da documentação │
│ │
│ ## Troubleshooting │
│ Problemas comuns e soluções │
│ │
│ ## Links Relacionados │
│ Docs relacionadas, recursos externos │
│ │
│ --- │
│ Última atualização: 2025-01-27 │
│ Dono: @username │
└─────────────────────────────────────────────────────────────┘
Dicas de Escrita
ESCRITA EFETIVA:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ✓ FAÇA: │
│ │
│ • Use voz ativa │
│ "Execute o comando" não "O comando deve ser executado" │
│ │
│ • Seja específico │
│ "Espere 30 segundos" não "Espere um pouco" │
│ │
│ • Inclua exemplos │
│ Código real > descrição abstrata │
│ │
│ • Use formatação │
│ Headers, bullets, code blocks │
│ │
│ • Teste suas instruções │
│ Siga seus próprios passos │
│ │
│ ✗ EVITE: │
│ │
│ • Jargão sem explicação │
│ • Passos implícitos │
│ • Screenshots de código │
│ • "Obviamente" ou "simplesmente" │
│ • Docs muito longas sem navegação │
└─────────────────────────────────────────────────────────────┘
Documentação no GitScrum
Usando Comentários de Tarefa
DOCUMENTAÇÃO EM TAREFAS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ BOAS PRÁTICAS: │
│ │
│ • Adicionar contexto importante na descrição │
│ • Documentar decisões nos comentários │
│ • Anexar screenshots de UI quando relevante │
│ • Linkar para docs externas │
│ • Registrar clarificações de requisitos │
│ │
│ EXEMPLO: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ TASK-456: Implementar rate limiting ││
│ │ ││
│ │ CONTEXTO: ││
│ │ API pública sofreu abuso. Precisamos limitar ││
│ │ requisições por IP. ││
│ │ ││
│ │ DECISÕES: ││
│ │ @alex 10:30 - Decidimos usar Redis para rate ││
│ │ limiting. Token bucket com 100 req/min. ││
│ │ ││
│ │ @sam 14:15 - Alinhado com infra, Redis já está ││
│ │ disponível em produção. ││
│ │ ││
│ │ DOCS: /docs/rate-limiting.md ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
Armadilhas Comuns
O Que Evitar
ANTI-PADRÕES DE DOCUMENTAÇÃO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ✗ DOCUMENTAÇÃO ZUMBI │
│ Docs antigas que ninguém atualiza mas todos citam │
│ → Arquive ou atualize │
│ │
│ ✗ DOCUMENTAÇÃO FANTASMA │
│ Docs que existem mas ninguém encontra │
│ → Melhore descoberta, links │
│ │
│ ✗ DOCUMENTAÇÃO VAMPIRA │
│ Suga tempo mas não dá valor │
│ → Questione se é necessária │
│ │
│ ✗ WIKI SPRAWL │
│ Centenas de páginas sem organização │
│ → Estruture, arquive o desnecessário │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ ✓ DOCS SAUDÁVEIS: │
│ │
│ • Têm dono definido │
│ • São atualizadas como parte do trabalho │
│ • Estão onde pessoas procuram │
│ • Respondem perguntas reais │
└─────────────────────────────────────────────────────────────┘