Uma introdução aos Design Docs
Introdução
Você já trabalhou em uma grande equipe? Se sim, já deve ter passado por ao menos uma dessas situações:
- Atuar em um código sem owners e sem documentação;
- Iniciar uma solução e só então descobrir que existiam alternativas melhores;
- Procurar PRs e tasks para relembrar as tarefas que trabalhou e dar visibilidade na sua performance review;
- Trazer uma iniciativa, e só então descobrir que outros times estão atuando nela, ou já atuaram no passado.
Comunicação e visibilidade entre os times serão sempre grandes desafios. E como lidar melhor com isso? Uma prática muito usada, especialmente nas Big Tech, são os Design Docs.
O que são os Design Docs?
Em resumo, eles são documentos feitos pelo time (especialmente pelas pessoas desenvolvedoras), com o objetivo de tornar claro e compartilhável todo o processo de desenvolvimento de uma solução. Para isso, é documentado o racional da solução adotada, alternativas, objetivos, arquitetura, entre outros pontos que detalharemos a seguir.
Mas, antes de mais nada é bom lembrarmos que seu processo de criação é tão importante quanto seu resultado final (o design doc em si), pois seu ciclo de vida é propositalmente diferente do normalmente adotado em uma documentação comum, como veremos abaixo.
Por que usá-los?
Toda pessoa desenvolvedora com alguma experiência sabe o quão importante é a documentação. Os Design Docs, tem os seguintes objetivos:
Objetivos
- Documentar o processo de decisão e a solução adotada;
- Incentivar o estudo do problema e análise de alternativas antes da codificação;
- Transmitir conhecimento e visibilidade entre times e senioridades.
Além disso, nunca é tarde para relembrar que escrever não é apenas um veículo de comunicação, mas uma forma de cristalizar ideias e encontrar falhas e gaps de conhecimento.
Então, por que na grande maioria das empresas falta documentação de qualidade?
Entre diversos motivos, acredito que podemos destacar:
- Desconexão dos ciclos de vida: codificação vs. documentação;
- Incentivos desalinhados;
- Cultura da empresa.
Desconexão dos ciclos de vida: codificação vs. documentação
Você trabalhou diversas horas em uma solução, as finalizou e está prestes a entregar, e só então começa a documentar tudo o que foi feito. Esse é um processo anti-natural, reduz a qualidade da documentação (quando ela é de fato feito), e se torna uma tarefa chata.
Podemos fazer um paralelo com a escrita de testes. O ciclo de vida mais comum na escrita de testes é terminar a implementação, e só então escrever os testes sofrendo dos mesmo problemas que acabamos de citar.
No caso dos testes, o TDD é um grande aliado que conecta melhor o ciclo de vida de codificação com o de escrita dos testes. Já na documentação, os Design Docs nos ajudam de forma análoga.
Incentivos desalinhados
“Me mostre os incentivos e lhe mostrarei o resultado” — Charlie Munger
É difícil argumentar contra o poder dos incentivos. Pensando nisso, uma prática que boa parte das Big Tech utilizam é tornar os Design Docs parte importante do processo de performance review, incentivando o uso e a qualidade deles.
Cultura da empresa
Esse é um problema mais amplo, e muitas vezes um sintoma da falta de maturidade/valorização técnica.
Algumas empresas simplesmente pouco valorizam a documentação. Mas, também é possível que os próprios desenvolvedores não deem o devido valor à documentação.
Pensando nesses problemas, os Design Docs apesar de não serem bala de prata, são uma ótima forma de melhorar a quantidade e qualidade da documentação existente.
Mas, é preciso saber como colocá-los em prática da forma correta, e é isso que veremos agora.
Como fazer um Design Doc?
Ciclo de vida
- Escrita do documento base;
- Review (por pessoas externas ao time, normalmente mais seniores ou contexto);
- Implementação e iteração;
- Manutenção e aprendizado.
(Observe que a criação inicial do design doc é feita antes mesmo da codificação e que o processo é bastante iterativo.)
Estrutura(exemplo):
- Cabeçalho: Autores, revisores, datas, tags para facilitar a indexação, etc;
- Overview: pequena introdução sobre o que o documento trata (um desenvolvedor sem contexto deve conseguir entender);
- Contexto: explicação dos motivos para a atividade;
- Objetivos: determinantes de que a atividade foi concluída com sucesso (é interessante serem objetivos e metrificáveis, quando possível);
- Non-goals: pontos que estão fora do escopo do que está sendo trabalhado nessa atividade;
- Alternativas: as alternativas que foram consideradas para a resolução do problema, explicando seus trade-offs e motivação da escolha;
- System design: explicação técnica da solução adotada, que pode ter code snippets, diagramas, database schemas e tudo que agregará no entendimento futuro da implementação (a maior parte do conteúdo normalmente estará aqui);
- Cross-cutting concerns: possíveis pontos de bloqueio, questões relacionadas à observabilidade, infra, segurança, etc.
Lembre-se que a estrutura acima é genérica e deve servir apenas de exemplo. Seguir um template muito rígido será contraproducente.
Conclusão
Agora que você já conhece melhor os Design Docs, espero que esse texto tenha lhe ajudado a reforçar ainda mais a importância da documentação não só para o time, mas de forma individual, nos fazendo pensar melhor antes de partir para o código e assim entender melhor o problema a ser resolvido (isso já é boa parte da solução do problema).
Talvez você esteja pensando em adotá-los de alguma forma em seu time, e isso é ótimo! Então, ficam algumas dicas.
Dicas para uma adoção produtiva:
- Utilizá-los apenas em tarefas de média/alta complexidade, onde de fato trará ganhos;
- Definir um padrão mínimo entre os documentos, não sendo ele demasiadamente rígido;
- Definir um local centralizador e organizado para o armazenamento dos documentos, facilitando a pesquisa;
- Deixar claro para os stakeholders (não só técnicos), a importância do processo e alinhar os incentivos.
FAQ
Por que um Design Doc e não uma “documentação comum”?
- O objetivo de um design doc não é apenas documentar a solução adotada e sua escrita inicial surge antes mesmo da implementação no código. Esse ciclo de vida é intencional e visa forçar o time a levar em conta corner cases, encontrar problemas mais cedo, compartilhar, buscar ideias de outros desenvolvedores e documentar o processo de decisão.
- Além disso, a cultura de uso de design docs, quando adotada amplamente na organização, contribui para um processo de performance review mais justo. Portanto, é fundamental levar em conta não apenas o documento em si, mas sim seu processo de criação e seu alinhamento de incentivos.
Esse processo não se tornará muito burocrático e lento?
- Se mal aplicado, sem dúvidas os ganhos não compensarão os custos do processo. Por isso é fundamental estudarmos a melhor forma de aplicarmos um processo como esse, iterarmos com melhorias contínuas e sempre levarmos em conta os objetivos de tal processo, que quando bem executado se tornará natural e sem atrito para os desenvolvedores, com ganhos claros, especialmente a médio/longo prazo.
Quando escrever um Design Doc?
- A maior parte das tarefas que boa parcela de nós desenvolvedores atuamos no dia a dia não tem complexidade suficiente para justificar a criação de um design doc. E é preciso que esteja claro para todos os objetivos dos design docs, uma vez que sua criação não é sempre necessária e não deve trazer um grande overhead na produtividade, mesmo a curto prazo.
- Apesar disso, essa decisão tende a ser bastante subjetiva e como time podemos chegar a boas heurísticas conforme implementamos e validamos a relação esforço-recompensa.
Com quem compartilhar?
- Em muitas organizações, os design docs são públicos para todos de área da empresa (ex: desenvolvedores backend, web, mobile). Mas, normalmente os autores compartilham ativamente o documento apenas com os stakeholders da atividade em questão.
Devo pedir review, de quem?
- O review em algumas organizações, especialmente as maiores, é obrigatório. Mas, não necessariamente devemos seguir esse padrão mais rígido, vale refletirmos e testarmos abordagens diferentes.
- Via de regra é pedido o review de pares mais seniores ou mais contexto de times cross quando aplicável (plataforma, segurança…)
Espero que essa leitura tenha sido útil e trazido insights para você! 😉
Aproveite para compartilhar esse texto para que mais pessoas conheçam e adotem essa prática.
Não esqueça também de deixar suas dúvidas e feedbacks nos comentários.
