8 min leitura • Guide 757 of 877
Gestão de Conhecimento para Times de Desenvolvimento
Conhecimento vai embora pela porta quando pessoas saem. O GitScrum ajuda times a documentar decisões, processos e aprendizados onde o trabalho acontece.
Tipos de Conhecimento
O Que Documentar
CATEGORIAS DE DOCUMENTAÇÃO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ARQUITETURA & DESIGN: │
│ • Diagramas de arquitetura do sistema │
│ • Documentação de API │
│ • Modelos de dados │
│ • Architecture Decision Records (ADRs) │
│ • Escolhas de tecnologia e justificativa │
│ │
│ PROCESSOS: │
│ • Procedimentos de deployment │
│ • Runbooks de plantão │
│ • Diretrizes de code review │
│ • Rituais de sprint │
│ • Resposta a incidentes │
│ │
│ ONBOARDING: │
│ • Guias de setup │
│ • Normas e expectativas do time │
│ • Contatos chave e papéis │
│ • Checklist da primeira semana │
│ • Gotchas comuns │
│ │
│ DECISÕES: │
│ • Por que escolhemos X em vez de Y │
│ • Contexto que informou decisões │
│ • Trade-offs considerados │
│ • Quando revisitar decisões │
│ │
│ APRENDIZADOS: │
│ • Insights de post-mortems │
│ • Ações de retrospectivas │
│ • Conhecimento tribal │
│ • Dicas e truques │
└─────────────────────────────────────────────────────────────┘
Localizações da Documentação
ONDE CONHECIMENTO VIVE:
┌─────────────────────────────────────────────────────────────┐
│ │
│ NO REPOSITÓRIO DE CÓDIGO: │
│ │
│ /docs │
│ ├── README.md Início rápido │
│ ├── CONTRIBUTING.md Como contribuir │
│ ├── architecture/ │
│ │ ├── overview.md Arquitetura do sistema │
│ │ └── decisions/ ADRs │
│ │ ├── 001-use-postgres.md │
│ │ └── 002-auth-approach.md │
│ ├── api/ Documentação de API │
│ └── runbooks/ Guias operacionais │
│ │
│ NA WIKI/NOTION: │
│ │
│ Handbook do Time │
│ ├── Processos do time │
│ ├── Agendas de reuniões │
│ ├── Papéis e responsabilidades │
│ └── Guia de onboarding │
│ │
│ NO GITSCRUM: │
│ │
│ • Contexto e requisitos de tarefas │
│ • Histórico de discussões │
│ • Justificativa de decisões │
│ • Links para docs relevantes │
│ │
│ PRINCÍPIO: │
│ Docs técnicos → perto do código │
│ Docs de processo → wiki compartilhada │
│ Contexto de tarefa → GitScrum │
└─────────────────────────────────────────────────────────────┘
Architecture Decision Records
Formato ADR
ARCHITECTURE DECISION RECORD:
┌─────────────────────────────────────────────────────────────┐
│ ADR-002: Usar PostgreSQL para Banco de Dados Principal │
├─────────────────────────────────────────────────────────────┤
│ │
│ STATUS: Aceito │
│ DATA: 2024-01-15 │
│ AUTORES: @alex, @maria │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ CONTEXTO: │
│ Precisamos de um banco de dados principal para dados de │
│ usuários, projetos e tarefas. Esperamos 100K usuários no │
│ primeiro ano, 1M até o terceiro ano. Time tem experiência │
│ com MySQL e PostgreSQL. │
│ │
│ DECISÃO: │
│ Usaremos PostgreSQL como nosso banco de dados principal. │
│ │
│ JUSTIFICATIVA: │
│ • Melhor suporte a JSON para schemas flexíveis │
│ • Capacidades superiores de full-text search │
│ • Forte conformidade ACID │
│ • Extensões ricas (PostGIS, etc.) │
│ • Comunidade ativa e madura │
│ │
│ ALTERNATIVAS CONSIDERADAS: │
│ 1. MySQL - Rejeitado: Suporte JSON inferior │
│ 2. MongoDB - Rejeitado: Consistência transacional │
│ 3. SQLite - Rejeitado: Não escala para produção │
│ │
│ CONSEQUÊNCIAS: │
│ ├── Time precisa manter expertise em PostgreSQL │
│ ├── Hosting via AWS RDS │
│ ├── Backup e recovery usando pg_dump │
│ └── Monitoramento com pg_stat │
│ │
└─────────────────────────────────────────────────────────────┘
Quando Criar ADRs
GATILHOS PARA ADR:
┌─────────────────────────────────────────────────────────────┐
│ │
│ CRIAR ADR QUANDO: │
│ ──────────────── │
│ ☑ Escolhendo tecnologia/framework │
│ ☑ Definindo padrão arquitetural │
│ ☑ Decisão afeta múltiplos componentes │
│ ☑ Trade-offs significativos envolvidos │
│ ☑ Provável que será questionado no futuro │
│ ☑ Decisão é difícil de reverter │
│ │
│ NÃO CRIAR ADR PARA: │
│ ────────────────── │
│ ☐ Decisões triviais │
│ ☐ Escolhas facilmente reversíveis │
│ ☐ Preferências pessoais de código │
│ ☐ Bugs ou fixes simples │
│ │
│ EXEMPLOS DE BONS ADRs: │
│ ───────────────────── │
│ • ADR-001: Usar microservices vs monolito │
│ • ADR-002: PostgreSQL como DB principal │
│ • ADR-003: REST vs GraphQL para API │
│ • ADR-004: Estratégia de autenticação │
│ • ADR-005: Framework de testes │
│ • ADR-006: Estratégia de CI/CD │
│ │
└─────────────────────────────────────────────────────────────┘
Runbooks Operacionais
Estrutura de Runbook
TEMPLATE DE RUNBOOK:
┌─────────────────────────────────────────────────────────────┐
│ │
│ # Runbook: Deploy em Produção │
│ │
│ ## Pré-requisitos │
│ ├── Acesso ao cluster Kubernetes │
│ ├── Credenciais AWS configuradas │
│ ├── VPN conectada │
│ └── Slack channel #deploys aberto │
│ │
│ ## Passos │
│ │
│ ### 1. Verificar prontidão │
│ ```bash │
│ # Verificar status do pipeline │
│ gh run list --workflow=ci.yml │
│ │
│ # Verificar staging │
│ curl https://staging.app.com/health │
│ ``` │
│ │
│ ### 2. Iniciar deploy │
│ ```bash │
│ # Deploy via script │
│ ./scripts/deploy.sh production v1.2.3 │
│ ``` │
│ │
│ ### 3. Verificar sucesso │
│ ```bash │
│ # Health check │
│ curl https://app.com/health │
│ │
│ # Verificar logs │
│ kubectl logs -f deployment/app -n production │
│ ``` │
│ │
│ ## Rollback │
│ Se problemas, executar: │
│ ```bash │
│ ./scripts/rollback.sh production │
│ ``` │
│ │
│ ## Troubleshooting │
│ | Problema | Solução | │
│ |----------|---------| │
│ | Pod não inicia | Verificar recursos/limites | │
│ | Health check falha | Verificar conexão DB | │
│ | Erros 500 | Verificar logs e métricas | │
│ │
└─────────────────────────────────────────────────────────────┘
Práticas de Compartilhamento
Sessões de Conhecimento
FORMATOS DE COMPARTILHAMENTO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ BROWN BAG / LUNCH & LEARN: │
│ ─────────────────────────── │
│ Frequência: Quinzenal │
│ Duração: 30-45 minutos │
│ Formato: Apresentação informal + Q&A │
│ │
│ Tópicos exemplo: │
│ • "Como funciona nosso sistema de filas" │
│ • "Por que escolhemos Kubernetes" │
│ • "Debugging de problemas de performance" │
│ • "Novas features do TypeScript 5" │
│ │
│ PAIR PROGRAMMING ROTATIVO: │
│ ─────────────────────────── │
│ • Toda semana, parear com pessoa diferente │
│ • Trabalhar em área desconhecida │
│ • Navegar ensinando, piloto aprendendo │
│ │
│ CODE REVIEW EDUCATIVO: │
│ ───────────────────── │
│ • Explicar "por quê" não só "o quê" │
│ • Linkar para docs relevantes │
│ • Rotacionar reviewers │
│ │
│ DEMO FRIDAY: │
│ ──────────── │
│ Sexta-feira: 30 min de demos do que foi construído │
│ • Cada pessoa mostra algo │
│ • Informal e celebratório │
│ • Espalha awareness do que está acontecendo │
│ │
└─────────────────────────────────────────────────────────────┘
Melhores Práticas
Checklist de Implementação
CHECKLIST DE GESTÃO DE CONHECIMENTO
═══════════════════════════════════
ESTRUTURA:
☐ Definir onde cada tipo de doc vive
☐ Criar templates padrão
☐ Estabelecer convenções de nomenclatura
☐ Configurar busca/indexação
PROCESSO:
☐ Incluir docs na Definition of Done
☐ Atribuir owners para seções
☐ Definir ciclo de revisão
☐ Criar gatilhos de atualização
CULTURA:
☐ Valorizar documentação
☐ Reconhecer bons documentadores
☐ Facilitar contribuição
☐ Tratar docs como código
MANUTENÇÃO:
☐ Auditoria trimestral de docs
☐ Remover conteúdo obsoleto
☐ Consolidar duplicatas
☐ Medir uso e feedback
Conhecimento bem gerenciado é conhecimento que realmente ajuda—acessível, atualizado e útil quando você precisa.