Design documents e RFCs
Design documents e RFCs
Como fazer documentação técnica que realmente ajude você, seu time e também sua carreira.
Recentemente, escrevi um design doc (também chamado de request for comments, ou RFC) no trabalho e recebi um feedback este de um Staff Engineer: "o conteúdo está bom, mas está um pouco desorganizado. Fica difícil localizar as partes mais importantes".
Isso me fez refletir sobre como podemos melhorar nossa documentação técnica. E como isso pode nos ajudar a crescer na carreira.
✨ O que esperar do artigo
Por que documentação técnica é importante para sua carreira
Como escrever RFCs e design docs que pessoas vão querer ler
Quando prototipar antes de documentar
Dicas práticas baseadas em experiências reais
Por que escrever documentação técnica?
A primeira coisa que precisamos entender: documentação não é burocracia.
Escrever clarifica nosso pensamento.
Quando colocamos nossas ideias no papel, somos forçados a organizá-las.
É comum percebermos falhas no nosso raciocínio apenas quando tentamos explicá-lo.
Empresas como Uber, Airbnb, GitLab e Shopify usam RFCs e design docs como parte fundamental do seu processo de desenvolvimento.
O motivo? Feedback cedo evita retrabalho depois.
Talvez vocês se lembrem dessa imagem do meu artigo de produto vs plataforma.
Ela mostra as etapas padrões do ciclo de vida de desenvolvimento de software.
Toda mudança que precisamos fazer até depois da etapa 2 é cada vez mais cara.
Se nossa arquitetura mudar durante a implementação, o trabalho será muito maior.
É através da escrita de design docs que conseguimos evitar esse re-trabalho.
Outras vantagens de escrever RFCs:
Conseguir feedback rapidamente. Tanto do lado de engenharia para ver se sua abordagem está correta. Quanto do lado de produto, para ver se os requisitos estão sendo todos cobertos.
Escalar você mesmo. Se você não criar um documento, as pessoas só vão poder ver suas ideias falando com você. E se seu projeto envolver mais gente, com mais pessoas você vai precisar falar. Ao ter um artefato externo, você consegue chegar em mais pessoas com menos tempo.
Promover uma cultura de escrita. Se alguém ver você escrevendo um bom RFC, essa pessoa poderá fazer o mesmo no futuro. Assim, a equipe toda consegue tirar as vantagens desses tipos de documento, e conseguem feedback com mais rapidez.
O poder dos protótipos
A escrita é importante. Mas, as vezes, quando temos um problema novo, pode ser que não tenhamos alguma base para já discutir sobre ele.
É aqui que entram os protótipos.
Protótipos são uma ferramenta poderosa para validar ideias rapidamente. Algumas dicas:
Seja claro que é temporário
Use uma tecnologia diferente da produção
Não perca tempo com testes ou código limpo
O objetivo é provar um conceito, não ter código perfeito
Concentre no que é incerto
Foque nas partes que você não tem certeza
Ignore o que já é bem entendido
Valide suas maiores suposições primeiro
Use para gerar discussões produtivas
Código real > discussões abstratas
Mais fácil criticar algo concreto
Ajuda a alinhar expectativas
Atenção: Resista à tentação de transformar o protótipo em código de produção. É tentador, mas geralmente é uma má ideia.
Quando documentar vs quando prototipar
Aqui está um framework que uso para decidir:
Problema conhecido, solução clara: Escreva o RFC primeiro
Você já fez algo similar antes
As tecnologias são familiares
Os riscos são bem entendidos
Problema complexo, muitas incertezas: Protótipo primeiro
Integrações com APIs novas
Arquiteturas que nunca tentamos
Muitas partes móveis e times envolvidos
Como fazer documentação que pessoas vão ler
Aqui está o segredo: pessoas são ocupadas. Ninguém tem tempo de ler um documento de 20 páginas.
O que funciona:
Seja conciso. Vá direto ao ponto. Um bom documento técnico deve ter 2-3 páginas no máximo.
Use diagramas. Uma imagem vale mais que mil palavras. Especialmente para:
Fluxos de dados
Arquitetura do sistema
Modelos de dados
Sequência de eventos
Proponha uma solução clara. Não liste todas as possibilidades. Escolha uma abordagem e defenda ela.
Destaque o que é importante. Use títulos, bullets e seções para guiar o leitor.
Um engenheiro, ao ler seu documento, está procurando principalmente pelas seguintes informações:
Entender como os dados estão organizados hoje
Porque estamos fazendo uma mudança
Quais são das mudanças no modelo de dados
1-2 diagramas de sequência ilustrando as como as mudanças vão ser executadas. Se puder, também coloque o design de alta fidelidade aqui (Figma).
Isso foi o que eu aprendi ao escrever minha última RFC. Especificamente do feedback de engenheiros senior e staff+.
Como estruturar seu documento
Use essa estrutura como base:
Contexto (1 parágrafo)
Qual o problema?
Por que precisamos resolver agora?
Proposta (1-2 parágrafos + diagramas)
Como vamos resolver?
Quais as mudanças principais?
Implementação (1-2 diagramas)
Sequência de eventos
Modelos de dados
Riscos e Alternativas (bullets)
O que pode dar errado?
Quais outras opções consideramos?
Comece simples.
Adicione mais sessões, conforme você vê necessidade.
Caso você use o Notion na sua empresa, você poe checar essa lista excelente de templates disponíveis pra ele. Feitos pelo próprio Notion.
Como revisar RFCs dos outros
Revisar RFCs é uma habilidade tão importante quanto escrevê-los. Algumas dicas:
Procure clareza
O problema está bem definido?
A solução é fácil de entender?
Os diagramas fazem sentido?
Questione premissas
As suposições fazem sentido?
Existem casos de borda não considerados?
A escalabilidade foi pensada?
Seja construtivo
Sugira melhorias específicas
Reconheça pontos positivos
Foque em melhorar a solução
Os principais erros que você pode cometer escrevendo RFCs
Documentar depois de construir
O RFC vira apenas uma formalidade
Time não está aberto a feedback
Perde-se a chance de evitar problemas cedo
Comum, mas não recomendado
Foco excessivo em detalhes técnicos
Muito código e pouca explicação do porquê
Diagramas complexos que só você entende
Falta contexto do problema sendo resolvido
Lembre-se: seu leitor pode não conhecer o sistema tão bem quanto você
Listar todas as opções possíveis
"Podemos usar X, Y ou Z para resolver isso..."
Não tomar uma posição clara
Deixar decisões em aberto
Melhor: proponha uma solução e defenda ela
Não considerar o público
Linguagem muito técnica para stakeholders de negócio
Muito contexto de negócio para um doc técnico
Misturar diferentes níveis de abstração
Sempre pense: quem precisa entender esse documento?
Não explicar o impacto no negócio
Focar só na solução técnica
Não explicar por que isso é importante
Não mostrar trade-offs de negócio
Todo projeto técnico existe para resolver um problema de negócio
Documentação muito longa
"Vou documentar tudo que sei sobre o sistema"
Detalhes que não são relevantes para decisão
Contexto histórico desnecessário
Mantenha o foco no que é importante agora
Poucos ou nenhum diagrama
Paredes de texto
Explicações que seriam mais claras visualmente
Fluxos complexos descritos em texto
Use diagramas para explicar fluxos, arquitetura e modelos de dados
Não revisar com stakeholders cedo
Esperar o documento ficar "perfeito"
Descobrir problemas fundamentais tarde
Perder chance de alinhar expectativas
Compartilhe rascunhos cedo e peça feedback
🌟 Resumo
Alterne entre documentação e protótipos baseado na incerteza do problema
Foque em ser conciso e visual - use diagramas sempre que possível
Protótipos são excelentes para validar ideias rapidamente
Uma boa documentação pode ser a diferença entre um projeto bem sucedido e um fracasso
Lembre-se: o objetivo não é ter documentação ou protótipos perfeitos. É comunicar ideias de forma efetiva e validar soluções rapidamente.
Se você quer ver exemplos de bons design docs, recomendo dar uma olhada no DesignDocs.dev. Tem uma coleção incrível de exemplos de empresas como Google, Sourcegraph e outras.
Caso você use o Notion, cheque essa lista.
Você gostou dessa edição? Se sim, tem duas coisas que você pode fazer para ajudar:
Se você acha que outra pessoa pode gostar desse artigo, ♻️ compartilhe e ❤️ curta. Ajuda muito na recomendação aqui do Substack.