Artigo original: How to write a good software design doc
Escrito por: Angela Zhang
Como engenheira de software, eu passo muito tempo lendo e escrevendo documentos de design. Após ter passado por centenas desses documentos, vi em primeira mão uma forte correlação entre bons documentos de design e o sucesso final do projeto.
Este artigo é minha tentativa de descrever o que torna ótimo um documento de design.
O artigo é dividido em 4 seções:
- Por que escrever um documento de design
- O que incluir em um documento de design
- Como escrevê-lo
- O processo que o envolve
Por que escrever um documento de design?
Um documento de design – também conhecido como especificação técnica – é uma descrição de como você planeja resolver um problema.
Já existem muitos escritos (textos em inglês) sobre a importância de escrever um documento de design antes de começar a programar. Portanto, tudo o que vou dizer aqui é:
Um documento de design é a ferramenta mais útil para garantir que o trabalho certo seja feito.
O principal objetivo de um documento de design é torná-lo mais eficaz, forçando você a pensar no design e a obter feedback dos outros. As pessoas frequentemente pensam que o objetivo de um documento de design é ensinar aos outros sobre algum sistema ou servir como documentação mais tarde. Embora esses possam ser efeitos colaterais benéficos, eles não são o objetivo em si.
Como regra geral, se você estiver trabalhando em um projeto que pode levar um mês ou mais de engenharia, você deve escrever um documento de design. Porém, não pare por aí – muitos projetos menores também poderiam se beneficiar de um minidocumento de design.
Ótimo! Se você ainda está lendo, você acredita na importância dos documentos de design. Entretanto, equipes de engenharia diferentes e até mesmo engenheiros dentro de uma mesma equipe, muitas vezes, escrevem documentos de design de modos muito diferentes. Portanto, vamos falar sobre o conteúdo, estilo e processo de um bom documento de design.
O que incluir em um documento de design?
Um documento de design descreve a solução para um problema. Como a natureza de cada problema é diferente, naturalmente, você gostaria de estruturar seu documento de design de modos diferentes.
Para começar, a seguir está uma lista de seções que você deve pelo menos considerar incluir em seu próximo documento de design:
Título e pessoas
O título de seu documento de design, os autores (que devem ser os mesmos da lista de pessoas que planejam trabalhar neste projeto), os revisores do documento (falaremos mais sobre isso na seção Processo, abaixo), e a data em que este documento foi atualizado pela última vez.
Visão geral
Um resumo de alto nível que todo engenheiro da empresa deve entender e usar para decidir se é útil para eles ler o resto do documento. Deve ter, no máximo, 3 parágrafos.
Contexto
Uma descrição do problema em questão, por que este projeto é necessário, o que as pessoas precisam saber para avaliar este projeto e como ele se encaixa na estratégia técnica, na estratégia do produto ou nas metas trimestrais da equipe.
Objetivos e não objetivos
A seção Objetivos deve:
- descrever o impacto de seu projeto – onde seu usuário pode ser outra equipe de engenharia ou mesmo outro sistema técnico
- especificar como medir o sucesso usando métricas – com ainda maior valor se você puder conectar a seção a um painel que rastreie essas métricas
"Não objetivos" são igualmente importantes para descrever quais problemas você não estará resolvendo para que todos saibam do que se está falando.
Marcos
Uma lista de pontos notáveis mensuráveis para que seu gerente de projeto e para que o gerente dele possam olhar a lista e saber aproximadamente quando diferentes partes do projeto estarão concluídas. Eu o encorajo a quebrar o projeto em marcos importantes para o usuário, se o projeto tiver mais de um mês de duração.
Use datas no calendário para levar em conta atrasos não relacionados, férias, reuniões e assim por diante. Deve ser algo parecido com isto:
Data de início: 7 de junho de 2022Marco nº 1 — Novo MVP do sistema em funcionamento em modo escuro: 28 de junho de 2022Marco nº 2 - Aposentar o sistema antigo: 4 de julho de 2022Encerramento: Adicionar os recursos X, Y e Z ao novo sistema: 14 de julho de 2022
Adicione uma subseção [Atualização] se a data final de entrega de alguns desses marcos mudar, para que as partes interessadas possam facilmente ver as estimativas mais atualizadas.
Solução existente
Além de descrever a implementação atual, você também deve percorrer um fluxo de exemplo de alto nível para ilustrar como os usuários interagem com esse sistema e/ou como os dados fluem através dele.
Uma história de usuário é uma ótima maneira de enquadrar isto. Tenha em mente que seu sistema pode ter diferentes tipos de usuários com diferentes casos de uso.
Solução proposta
Algumas pessoas chamam isso de seção de Arquitetura técnica. Mais uma vez, percorra uma história de usuário para tornar isso concreto. Sinta-se à vontade para incluir muitas subseções e diagramas.
Forneça um quadro geral primeiro, depois preencha com muitos detalhes. Busque um mundo ideal onde você possa escrever essa seção e depois tirar férias em alguma ilha deserta, enquanto outro engenheiro da equipe pode simplesmente ler e implementar a solução do jeito que você a descreveu.
Soluções alternativas
O que mais você considerou quando chegou à solução acima? Quais são os prós e contras das alternativas? Você já considerou comprar uma solução de terceiros – ou usar uma solução de código aberto – que resolva esse problema em vez de criar sua própria solução?
Testabilidade, monitoramento e alerta
Gosto de incluir esta seção, porque as pessoas muitas vezes tratam essa parte como algo a se pensar depois ou simplesmente a ignoram. Quase sempre, isso volta para incomodar mais tarde, quando as coisas se quebram e eles não têm ideia de como ou por quê.
Impacto entre equipes
Como isso aumentará a carga de chamadas de solução de problemas e qual o impacto disso para a equipe de dev-ops?
Quanto dinheiro vai custar?
Causa alguma regressão de latência para o sistema?
Expõe alguma vulnerabilidade de segurança?
Quais são algumas das consequências negativas e dos efeitos colaterais?
Como a equipe de suporte poderia comunicar isso aos clientes?
Perguntas abertas
Qualquer assunto em aberto sobre o qual você não tenha certeza, decisões controversas que você gostaria que os leitores ponderassem a respeito, sugestões de trabalho futuro e assim por diante. Um nome, de certo modo, irônica para esta seção são as "incógnitas conhecidas".
Escopo detalhado e linha de tempo
Esta seção será lida, em geral, apenas pelos engenheiros que trabalham neste projeto, seus líderes técnicos e seus gerentes. Portanto, esta seção pode ficar ao final do documento.
Essencialmente, esta é a divisão de como e quando você planeja executar cada parte do projeto. Há muita coisa que entra na delimitação precisa do escopo. Então, você pode ler este artigo (texto em inglês) para saber mais sobre a delimitação do escopo.
Também tenho a tendência de tratar esta seção do documento de design como um rastreador das tarefas em andamento. Portanto, eu a atualizo sempre que minha estimativa de escopo muda. Isso, porém, é mais uma preferência pessoal.
Como escrevê-lo
Agora que falamos sobre o que entra em um bom documento de design, vamos falar sobre o estilo de escrita. Prometo que será diferente de sua aula de inglês do ensino médio.
Escreva da maneira mais simples possível
Não tente escrever como os trabalhos acadêmicos que você leu. Eles são escritos para impressionar os revisores dos periódicos. Seu documento é escrito para descrever a sua solução e obter feedback de seus colegas de equipe. Você pode obter clareza ao usar:
- Palavras simples
- Frases curtas
- Listas com pontos e/ou listas numeradas
- Exemplos concretos, como "Usuário Alice conecta sua conta bancária, então ..."
Adicione muitos gráficos e diagramas
Os gráficos podem muitas vezes ser úteis para comparar várias opções potenciais. Os diagramas são, geralmente, mais fáceis de analisar do que o texto. Tive sorte com o aplicativo de Desenhos do Google para criar diagramas.
Dica profissional: lembre-se de adicionar um link para a versão editável do diagrama sob a captura de tela para que você possa facilmente atualizá-lo mais tarde quando as coisas mudarem inevitavelmente.
Inclua números
A escala do problema, muitas vezes, determina a solução. Para ajudar os revisores a ter uma noção do estado das coisas, inclua números reais como nº de linhas de bancos de dados, nº de erros de usuários, latência – e como isso é escalável com o uso. Lembra-se das suas notações de Big-O?
Tente ser engraçado
Uma especificação não é um trabalho acadêmico. Além disso, as pessoas gostam de ler coisas engraçadas. Então, essa é uma boa maneira de manter o leitor engajado. Não exagere, porém, a ponto de tirar o foco da ideia principal.
Se você, como eu, tem dificuldade em ser engraçado, Joel Spolsky (obviamente conhecido por seus talentos cômicos...) tem esta dica:
Uma das maneiras mais fáceis de ser engraçado é ser específico quando não é chamado para [Exemplo:] Em vez de dizer "pessoas com interesses especiais", dizer "cultivadores de abacate canhotos".
Faça o teste do cético
Antes de enviar seu documento de design a outras pessoas para revisão, examine-o fingindo ser o revisor. Quais perguntas e dúvidas você pode ter sobre este design? Então, trate-as de antemão.
Faça o teste das férias
Se você passar um tempo maior em férias e sem acesso à internet, alguém de sua equipe pode ler o documento e implementar as coisas do modo como você pretendia?
O principal objetivo de um documento de design não é o compartilhamento de conhecimento, mas é uma boa maneira de avaliar a clareza para que outros possam realmente dar a você um feedback útil.
Processo
Ah, sim, a temida palavra começando com P. Os documentos de design ajudam a obter feedback antes que você gaste muito tempo implementando a solução errada ou a solução para o problema errado. Há muita coisa envolvida em se obter um bom feedback, mas isso é para um artigo posterior. Por enquanto, vamos apenas falar especificamente sobre como escrever o documento de design e obter feedback para ele.
Antes de mais nada, todos que trabalham no projeto devem fazer parte do processo de design. Não é problema se a liderança tecnológica acabar impulsionando muitas das decisões, mas todos devem estar envolvidos na discussão e aderir ao design. Portanto, quando falamos "você" ao longo deste artigo, lembre-se de que ele se aplica a todas as pessoas no projeto.
Em segundo lugar, o processo de design não significa que você está olhando para as ideias teóricas do quadro branco. Sinta-se à vontade para colocar as mãos à obra e fazer um protótipo de soluções potenciais. Isso não é a mesma coisa que começar a escrever o código de produção para o projeto antes de escrever um documento de design. Não faça isso. Você deve, no entanto, se sentir absolutamente livre para escrever algum código enjambrado e que você possa descartar depois apenas para validar uma ideia. Para garantir que você só escreva código exploratório, faça com que seja uma regra que nenhum código desse protótipo seja inserido na branch master/main.
Depois disso, ao começar a ter alguma ideia de como realizar seu projeto, faça o seguinte:
- Peça a um engenheiro ou líder técnico experiente em sua equipe para ser seu revisor. O ideal seria que fosse alguém bem respeitado e/ou familiarizado com os casos de ponta do problema. Convença-os com algum presentinho, se necessário.
- Vá com o colega a uma sala de conferências com um quadro branco.
- Descreva o problema que você está enfrentando para este engenheiro (este é um passo muito importante, não o pule!).
- Explique a implementação que você tem em mente e convença o engenheiro de que esta é a coisa certa a ser construída.
Fazer tudo isso antes mesmo de começar a escrever seu documento de design permite que você receba feedback o mais rápido possível, antes de investir mais tempo e se apegar a qualquer solução específica. Muitas vezes, mesmo que a implementação permaneça a mesma, seu revisor é capaz de apontar os casos limite que você precisa cobrir, indicar quaisquer áreas potenciais de confusão e antecipar dificuldades que você possa encontrar mais tarde.
Então, depois de escrever um rascunho do seu documento de design, peça ao mesmo revisor que o leia novamente, e carimbe-o adicionando o seu nome como revisor na seção Título e Pessoas do documento de design. Isto cria um incentivo adicional e responsabilidade para o revisor.
Sobre essa nota, considere a adição de revisores especializados (tais como SREs e engenheiros de segurança) para aspectos específicos do design.
Assim que você e os revisores assinarem, sinta-se à vontade para enviar o documento de design à sua equipe para feedback adicional e compartilhamento de conhecimento. Sugiro que este processo de coleta de feedback seja limitado no tempo a cerca de 1 semana para evitar atrasos prolongados. Comprometa-se a responder a todas as perguntas e comentários que as pessoas deixarem durante essa semana. Deixar comentários pendentes = muito azar.
Finalmente, se houver muito conflito entre você, seu revisor e outros engenheiros que leem o documento, recomendo fortemente a consolidação de todos os pontos de conflito na seção Discussão do seu documento. Então, marque uma reunião com as diferentes partes para falar pessoalmente sobre essas discordâncias.
Sempre que um tópico de discussão tiver mais de 5 comentários, passar para uma discussão presencial tenderá a ser muito mais eficiente. Tenha em mente que você ainda é responsável por fazer a chamada final, mesmo que nem todos consigam chegar a um consenso.
Ao falar com um colega recentemente sobre isso, soube que ele tem um processo semelhante, exceto pelo fato de que, além de ter um engenheiro experiente ou líder técnico em sua equipe como revisor, eles também sugerem ter um engenheiro de uma equipe diferente para revisar o documento. Eu não tentei isso, mas certamente posso ver o quanto ajuda obter feedback de pessoas com perspectivas diferentes e melhorar a legibilidade geral do documento.
Uma vez que você tenha feito tudo o que vemos acima, é hora de começar a implementação! Para ganhar uns pontos a mais, trate este documento de projeto como um documento vivo à medida que você implementa o design. Atualize o documento toda vez que aprender algo que o leve a fazer mudanças na solução original ou atualizar seu escopo. Você vai me agradecer mais tarde quando não tiver que explicar as coisas repetidas vezes a todas as partes interessadas.
Por fim, vamos realmente fazer um metadiscurso por um segundo: Como avaliamos o sucesso de um documento de design?
Meu colega de trabalho, Kent Rakip, tem uma boa resposta para isso: Um documento de design é bem-sucedido se o ROI correto de trabalho for feito. Isso significa que um documento de design bem-sucedido pode realmente levar a um resultado como este:
- Você gasta 5 dias escrevendo o documento de projeto, o que força você a pensar em diferentes partes da arquitetura técnica
- Você recebe o feedback de revisores de que
Xé a parte mais arriscada da arquitetura proposta - Você decide implementar
Xprimeiro para reduzir o risco do projeto - 3 dias depois, você descobre que
Xnão é possível ou é muito mais difícil do que você pretendia originalmente - Você decide parar de trabalhar neste projeto e prioriza outros trabalhos em seu lugar
No início deste artigo, dissemos que o objetivo de um documento de design é garantir que o trabalho certo seja feito. No exemplo acima, graças a este documento de design, em vez de desperdiçar potencialmente meses apenas para abandonar este projeto mais tarde, você gastou apenas 8 dias. Parece-me um resultado muito bem-sucedido.
Para creditar aqueles que merecem, eu aprendi muito do que mostro acima ao trabalhar ao lado de alguns engenheiros incríveis na Plaid e na Quora.
Se você gostou deste artigo, siga a autora no Twitter para mais artigos sobre engenharia, processos e sistemas de back-end.