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:

1. 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.
2. 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.
3. 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:

1. 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
2. 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
3. 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:

1. 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
2. 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:

1. Seja conciso. Vá direto ao ponto. Um bom documento técnico deve ter 2-3 páginas no máximo.
2. Use diagramas. Uma imagem vale mais que mil palavras. Especialmente para:
   • Fluxos de dados
   • Arquitetura do sistema
   • Modelos de dados
   • Sequência de eventos
3. Proponha uma solução clara. Não liste todas as possibilidades. Escolha uma abordagem e defenda ela.
4. 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+.

Um exemplo de um diagrama de sequência, mostrando como uma funcionalidade de busca pode funcionar. Escrever isso em palavras seria mais difícil do que usar uma imagem. Fonte: Create a sequence diagram - draw.io.

Como estruturar seu documento

Use essa estrutura como base:

1. Contexto (1 parágrafo)
   • Qual o problema?
   • Por que precisamos resolver agora?
2. Proposta (1-2 parágrafos + diagramas)
   • Como vamos resolver?
   • Quais as mudanças principais?
3. Implementação (1-2 diagramas)
   • Sequência de eventos
   • Modelos de dados
4. 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:

1. Procure clareza
   • O problema está bem definido?
   • A solução é fácil de entender?
   • Os diagramas fazem sentido?
2. Questione premissas
   • As suposições fazem sentido?
   • Existem casos de borda não considerados?
   • A escalabilidade foi pensada?
3. 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.

Esse artigo foi publicado na minha newsletter, Dev na Gringa.

Se você gosta do meu conteúdo, considere se inscrever para receber diretamente por e-mail.