Gestão de Conhecimento para Times de Desenvolvimento
Capture e compartilhe conhecimento do time efetivamente. Construa documentação que ajuda, não atrapalha.
8 min de leitura
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 │
│ │
│ │
│ ### 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.