Documentação em engenharia de Software | Arquitetura
- Documentação em engenharia de Software | Arquitetura
Tipos de documentos em engenharia de software
Em times de tecnologia, nem toda informação deve ir para o mesmo tipo de documento. Cada documento existe para atender um objetivo específico: decidir, discutir, detalhar, registrar ou aprender com falhas.
A tabela apresentada organiza isso em cinco formatos comuns:
| Tipo | Quando usar | Foco | Tamanho | Momento |
|---|---|---|---|---|
| ADR | Registrar decisão tomada | Uma decisão | Curto | Depois da decisão |
| Design Doc | Apresentar solução técnica | Arquitetura e design | Médio/Longo | Antes da implementação |
| RFC | Coletar feedback amplo | Discussão aberta | Variável | Antes da decisão |
| Tech Spec | Detalhar implementação | Código, estruturas | Médio | Depois do design |
| Postmortem | Incidentes | Causa e ações | Médio | Depois do incidente |
1. ADR
O que é
ADR significa Architecture Decision Record.
É um documento curto usado para registrar uma decisão técnica já tomada, junto com seu contexto e justificativa.
Quando usar
Use ADR quando o time já decidiu algo importante, por exemplo:
- escolher SignalR em vez de MQTT
- adotar Redis como backplane
- separar uma API em dois serviços
- definir um padrão de autenticação
Foco
O foco do ADR é uma decisão específica.
Ele não existe para discutir todas as possibilidades em profundidade, mas para deixar claro:
- qual decisão foi tomada
- por que ela foi tomada
- quais alternativas foram consideradas
- quais consequências isso traz
Momento
Normalmente é escrito depois da decisão.
Ou seja, o ADR registra a decisão para consulta futura, evitando dúvidas como:
- “por que fizemos isso?”
- “quem decidiu isso?”
- “qual problema isso resolvia?”
Tamanho
Geralmente curto.
Estrutura comum
- Contexto
- Decisão
- Alternativas consideradas
- Consequências
Exemplo
Decidimos usar SignalR como canal de envio de comandos para clientes desktop por melhor integração com .NET, suporte a fallback de transporte e menor complexidade operacional que MQTT no cenário atual.
2. Design Doc
O que é
O Design Doc é o documento usado para apresentar a solução técnica antes de implementar.
Ele descreve como o sistema ou funcionalidade será desenhado.
Quando usar
Use quando a mudança exige análise técnica mais ampla, por exemplo:
- criação de um novo serviço
- mudança arquitetural relevante
- integração com outro sistema
- alteração de fluxo crítico
- solução com impacto em escalabilidade, segurança ou observabilidade
Foco
O foco é a arquitetura e o design da solução.
Ele responde perguntas como:
- qual problema queremos resolver?
- como a solução será estruturada?
- quais componentes estarão envolvidos?
- quais riscos existem?
- quais trade-offs foram aceitos?
Momento
É escrito antes da implementação.
Tamanho
Normalmente médio ou longo, porque precisa detalhar o raciocínio da solução.
Estrutura comum
- Problema
- Objetivos
- Escopo
- Solução proposta
- Arquitetura
- Fluxos
- Dependências
- Riscos
- Trade-offs
- Plano de rollout
Exemplo
Um Design Doc para um sistema de envio de comandos poderia detalhar:
- API de orquestração
- Hub SignalR
- uso de grupos por CNPJ
- Redis backplane
- fluxo assíncrono de retorno
- estratégia de autenticação
- observabilidade e health checks
3. RFC
O que é
RFC significa Request for Comments.
É um documento criado para abrir discussão e coletar feedback antes de tomar uma decisão.
Quando usar
Use quando ainda não há decisão fechada e você quer envolver outras pessoas na análise.
Exemplos:
- escolher entre SSE, SignalR e MQTT
- avaliar gateway APISIX vs Kong
- discutir estratégia de versionamento de API
- propor mudança estrutural com impacto em vários times
Foco
O foco da RFC é a discussão aberta.
Ela existe para levantar opiniões, riscos, objeções e sugestões.
Momento
É escrita antes da decisão.
Tamanho
Variável, porque depende da complexidade do tema.
Estrutura comum
- Contexto
- Problema
- Proposta inicial
- Alternativas
- Perguntas em aberto
- Impactos esperados
- Pontos para feedback
Exemplo
Estamos avaliando o canal de comunicação com 6 mil clientes desktop. As opções são SignalR, MQTT e SSE. Esta RFC busca feedback sobre confiabilidade, custo operacional, facilidade de integração e limites de payload.
Diferença entre RFC e ADR
A diferença central é simples:
- RFC: discute antes de decidir
- ADR: registra depois de decidir
4. Tech Spec
O que é
A Tech Spec é o documento que detalha a implementação de uma solução que já foi desenhada.
Se o Design Doc fala “o que será construído” em nível arquitetural, a Tech Spec aprofunda “como será implementado”.
Quando usar
Use quando a direção da solução já está definida e agora é necessário especificar detalhes técnicos de execução.
Exemplos:
- contratos de API
- classes e interfaces
- estrutura de banco
- eventos e filas
- validações
- estratégia de retry
- formato de payload
- comportamento de erro
Foco
O foco é código, estruturas e implementação.
Momento
Geralmente depois do design.
Tamanho
Normalmente médio.
Estrutura comum
- Visão geral técnica
- Endpoints
- Modelos de dados
- Regras de negócio
- Fluxo detalhado
- Estratégia de erro
- Observabilidade
- Testes
- Critérios de aceite técnicos
Exemplo
Uma Tech Spec pode detalhar:
- endpoint
POST /envio-comando/{cnpj} - payload esperado
- resposta com
requestId - nomes dos grupos SignalR
- extração do CNPJ do JWT
- regras de timeout
- contratos de retorno
- métricas expostas
5. Postmortem
O que é
O Postmortem é o documento criado depois de um incidente para registrar o que aconteceu, por que aconteceu e o que será feito para evitar recorrência.
Quando usar
Use após:
- indisponibilidade
- falha crítica
- perda de mensagens
- degradação severa
- incidente de segurança
- comportamento inesperado em produção
Foco
O foco está em causa e ações.
O objetivo não é culpar pessoas, mas entender o sistema e melhorar o processo.
Momento
É escrito depois do incidente.
Tamanho
Geralmente médio.
Estrutura comum
- Resumo do incidente
- Impacto
- Linha do tempo
- Causa raiz
- Fatores contribuintes
- Mitigação aplicada
- Ações corretivas
- Ações preventivas
- Lições aprendidas
Exemplo
Durante uma janela de pico, clientes não recebiam comandos em tempo real devido a falha de sticky session no proxy combinada com reconexões intermitentes. A ação corretiva foi ajustar o balanceamento e revisar a estratégia de afinidade de sessão.
Como escolher o documento certo
Uma forma prática de decidir é esta:
Use RFC
quando ainda está debatendo a melhor solução.
Use ADR
quando a decisão já foi tomada e você quer registrá-la.
Use Design Doc
quando precisa apresentar a solução técnica antes de construir.
Use Tech Spec
quando já sabe a solução e precisa descrever a implementação.
Use Postmortem
quando ocorreu um incidente e o time precisa aprender com ele.
Relação entre eles no fluxo de trabalho
Muitas vezes esses documentos aparecem em sequência:
-
RFC abre a discussão
-
ADR registra a decisão escolhida
-
Design Doc apresenta a arquitetura da solução
-
Tech Spec detalha a implementação
-
Postmortem registra aprendizados caso haja incidente em produção
Nem todo projeto precisa de todos eles, mas essa separação ajuda muito a evitar confusão entre:
- discutir
- decidir
- desenhar
- implementar
- aprender
Resumo prático
| Tipo | Pergunta que ele responde |
|---|---|
| ADR | Que decisão tomamos e por quê? |
| Design Doc | Como essa solução será desenhada? |
| RFC | O que estamos propondo e que feedback precisamos? |
| Tech Spec | Como isso será implementado tecnicamente? |
| Postmortem | O que aconteceu no incidente e o que faremos agora? |
Regra simples para não errar
Se estiver em dúvida, pense assim:
- quero discutir → RFC
- quero registrar decisão → ADR
- quero mostrar a solução → Design Doc
- quero detalhar implementação → Tech Spec
- quero analisar incidente → Postmortem