A cultura de escrever Design Docs no Google (2020)
(industrialempathy.com)- No Google, um Design Doc é um documento que organiza o contexto do problema, a estratégia de implementação em alto nível e as principais decisões de design antes da codificação, reduzindo riscos quando o custo de mudar o design ainda é baixo
- O valor do documento não está em explicar o código pronto, mas em explicitar trade-offs e alternativas, para que a organização compartilhe a mesma base para tomar decisões
- Um bom Design Doc inclui, de forma adequada ao projeto, contexto e escopo, objetivos e não objetivos, o design em si, alternativas consideradas e preocupações transversais como segurança, privacidade e observabilidade
- Se o design já estiver claro ou se o documento apenas listar etapas de implementação, o overhead de escrever e revisar um Design Doc pode ser maior do que os benefícios
- O documento passa por escrita, revisão, atualização durante a implementação, manutenção e aprendizado; se o design mudar antes do lançamento, é melhor atualizar o documento junto
O papel do Design Doc
- No Google, um Design Doc é um documento relativamente informal criado pelo principal autor de um sistema de software ou aplicação antes de iniciar um projeto de codificação
- Ele registra a estratégia de implementação em alto nível e as decisões centrais de design, mas mais importante do que uma simples lista de decisões são os trade-offs que mostram por que essas escolhas foram feitas
- Como o objetivo da engenharia de software não é produzir código por si só, mas resolver problemas, no início de um projeto um texto não estruturado pode ser mais conciso e fácil de entender do que código
- O Design Doc exerce vários papéis no ciclo de vida de desenvolvimento
- Descobrir questões de design cedo, quando o custo de mudança ainda é baixo
- Formar consenso de design dentro da organização
- Evitar que preocupações transversais como segurança, privacidade e observabilidade sejam esquecidas
- Ampliar o conhecimento de engenheiros seniores por toda a organização
- Preservar a memória organizacional sobre decisões de design
- Servir como artefato que resume o portfólio técnico do autor
Estrutura básica de um Design Doc
- Não existe um template rígido para Design Docs, e o primeiro princípio é escolher o formato mais adequado para o projeto específico
- Ainda assim, uma estrutura frequentemente útil pode ser organizada em contexto e escopo, objetivos e não objetivos, o design em si, alternativas consideradas, preocupações transversais e um tamanho apropriado
-
Contexto e escopo
- Fornece uma visão geral aproximada do ambiente em que o novo sistema será inserido e do que de fato será construído
- Como não é um documento de requisitos, deve ser conciso e focado em permitir que o leitor entenda rapidamente o contexto
- É possível assumir algum conhecimento prévio, e detalhes podem ser ligados por links
- Esta seção deve se concentrar em fatos objetivos de contexto
-
Objetivos e não objetivos
- Resume os objetivos do sistema e, às vezes ainda mais importante, os não objetivos em uma curta lista de bullets
- Não objetivos não são a simples negação de um objetivo, como “o sistema não pode travar”, mas itens que poderiam ter sido objetivos e foram explicitamente excluídos
- Em design de banco de dados, conformidade com ACID é um bom exemplo de algo que é importante saber se é objetivo ou não objetivo
- Mesmo que algo seja um não objetivo, ainda é possível escolher uma solução que ofereça essa propriedade se isso não trouxer trade-offs que prejudiquem os objetivos
Como escrever o design em si
- A seção do design em si deve começar por uma visão geral e descer para os detalhes
- O Design Doc é o lugar para registrar os trade-offs surgidos no design de software
- Com base nos fatos de contexto e nos requisitos expressos como objetivos e não objetivos, deve-se propor uma solução e mostrar por que ela atende melhor aos objetivos
- Uma vantagem do formato documental é a flexibilidade para escolher a forma de expressão mais adequada ao conjunto de problemas
-
Diagrama de contexto do sistema
- Em muitos documentos, um system-context-diagram pode ser útil
- Esse diagrama mostra o sistema como parte de um ambiente técnico maior, ajudando o leitor a entender o novo design dentro de um contexto que ele já conhece
-
APIs e armazenamento de dados
- Se o sistema em questão expõe uma API, geralmente é bom esboçar essa API
- Deve-se evitar copiar e colar definições formais de interface ou de dados
- Essas definições tendem a ficar prolixas, incluir detalhes desnecessários e envelhecer rapidamente
- O foco deve estar nas partes relevantes para o design e seus trade-offs
- Sistemas que armazenam dados devem tratar de como esses dados serão armazenados e em que forma aproximada
- Em vez de colar a definição completa do schema, é melhor explicar os pontos relacionados às decisões de design
-
Código e pseudocódigo
- Em geral, é melhor colocar pouco código em um Design Doc
- Exceto ao explicar um novo algoritmo, pseudocódigo também deve ser usado raramente
- Se houver um protótipo que demonstre que o design é viável, pode-se fazer link para ele quando apropriado
O grau de restrição muda a forma do documento
- Um dos principais fatores que influenciam o design de software e a forma de um Design Doc é o grau de restrição do espaço de soluções
- Em uma ponta, há projetos greenfield em que só existem os objetivos e praticamente qualquer solução é possível
- Esses documentos podem cobrir um escopo amplo, mas precisam definir rapidamente regras para reduzir o espaço a um conjunto administrável de soluções
- Na outra ponta, há sistemas em que as soluções possíveis estão bem definidas, mas não está claro como combiná-las para atingir os objetivos
- Pode ser um sistema legado difícil de mudar
- Pode ser o design de uma biblioteca que precisa funcionar dentro das restrições da linguagem de programação hospedeira
- Nesses casos, pode ser relativamente fácil listar o que é possível fazer, mas é preciso combinar essas opções de forma criativa para atingir o objetivo
- Se várias soluções forem imperfeitas, o documento deve se concentrar em escolher a melhor com base nos trade-offs identificados
Alternativas e preocupações transversais
-
Alternativas consideradas
- Esta seção lista designs alternativos que poderiam ter alcançado um resultado semelhante de forma razoável
- O foco deve estar nos trade-offs de cada design e em como esses trade-offs levaram à escolha final
- Soluções que não foram escolhidas podem ser tratadas de forma concisa, mas esta seção é muito importante no documento
- Ela deve mostrar por que outras soluções que o leitor poderia considerar são menos desejáveis à luz dos objetivos do projeto
-
Preocupações transversais
- Por meio desta seção, a organização pode garantir que preocupações transversais como segurança, privacidade e observabilidade sejam sempre consideradas
- Normalmente, ela se torna uma seção curta explicando como cada preocupação afeta o design e como será tratada
- A equipe deve definir quais preocupações serão consideradas padrão em seu contexto
- Projetos do Google exigem um Design Doc de privacidade separado por causa de sua importância, além de revisões dedicadas para privacidade e segurança
- A conclusão dessas revisões é exigida até o momento do lançamento do projeto
- A melhor prática é colaborar o mais cedo possível com as equipes de privacidade e segurança para que o design já reflita isso desde o início
- Se houver documentação dedicada para esse tema, o Design Doc central pode referenciá-la sem repetir os detalhes
Tamanho e quando pode não ser necessário escrever
-
Tamanho apropriado
- Um Design Doc deve ser detalhado o suficiente, mas curto o bastante para que pessoas ocupadas realmente o leiam
- Em projetos grandes, algo em torno de 10–20 páginas parece ser um bom ponto de equilíbrio
- Se ficar muito maior do que isso, pode ser melhor dividir o problema em subproblemas mais gerenciáveis
- Também é possível ter mini Design Docs de 1–3 páginas
- Eles são especialmente úteis para melhorias incrementais ou subtarefas de projetos ágeis
- Seguem as mesmas etapas de documentos longos, mas de forma mais concisa e focada em um conjunto limitado de problemas
-
Quando pode não ser necessário escrever
- Escrever um Design Doc traz overhead
- A decisão de escrever ou não depende de os benefícios, como consenso de design, documentação e revisão sênior, superarem o custo de produzir o documento
- O principal critério é se o problema de design é ambíguo
- Ele pode ser ambíguo por causa da complexidade do problema, da complexidade da solução, ou de ambos
- Se não houver ambiguidade, o valor do processo de documentação é pequeno
- Se o documento for na prática um manual de implementação, talvez não seja necessário um Design Doc
- Se ele apenas disser “vamos implementar assim”, sem explicar trade-offs, alternativas e decisões, talvez tivesse sido melhor começar logo a programar
- Se a solução for tão clara que não existam trade-offs, o valor do documento é baixo
- O overhead de escrever e revisar um Design Doc pode não combinar com prototipagem e iteração rápida
- Seguir metodologias ágeis não significa que se possa deixar de pensar cuidadosamente na solução para um problema conhecido
- A própria prototipagem pode fazer parte da criação do Design Doc, e “nós tentamos e funciona” pode ser uma base forte para uma escolha de design
O ciclo de vida do Design Doc
- O ciclo de vida de um Design Doc é composto por quatro etapas
- Escrita e iteração rápida
- Revisão
- Implementação e iteração
- Manutenção e aprendizado
-
Escrita e iteração rápida
- O documento pode ser escrito por um único autor ou em coautoria
- Depois disso, ele é compartilhado com colegas que conhecem melhor o espaço do problema, e passa por iterações rápidas
- Perguntas de esclarecimento e sugestões desses colegas ajudam o documento a chegar a uma primeira versão relativamente estável
- No Google, há engenheiros e equipes que preferem criar documentos com ferramentas de controle de versão e revisão de código, mas a maioria dos Design Docs é escrita no Google Docs e usa bastante seus recursos de colaboração
-
Revisão
- Na etapa de revisão, o documento é compartilhado com um público mais amplo do que os colaboradores próximos do autor original
- A revisão pode agregar muito valor, mas também pode virar uma armadilha de overhead, por isso deve ser tratada com cuidado
- Uma forma leve é enviar o documento para uma mailing list mais ampla da equipe, dando às pessoas a chance de analisá-lo
- As discussões acontecem principalmente nas threads de comentários do próprio documento
- Uma forma mais pesada é uma reunião formal de revisão de design, em que o autor apresenta o documento a leitores engenheiros seniores
- Muitas equipes no Google têm reuniões regulares para esse tipo de revisão
- Esperar por essas reuniões pode desacelerar significativamente o processo de desenvolvimento
- Isso pode ser amenizado buscando diretamente o feedback mais importante e evitando que a revisão mais ampla se torne um bloqueio para o progresso
- Quando o Google era uma empresa menor, era comum enviar designs para uma única mailing list central e deixar que engenheiros seniores revisassem quando tivessem tempo
- Essa abordagem tinha a vantagem de criar uma cultura de design de software relativamente uniforme em toda a empresa
- À medida que a organização de engenharia cresceu muito, tornou-se difícil manter essa abordagem centralizada
- O principal valor da revisão é criar oportunidades para que a experiência acumulada da organização influencie o design
- Em especial, a etapa de revisão ajuda de forma consistente a garantir que o design considere preocupações transversais como observabilidade, segurança e privacidade
- O valor central da revisão não está apenas em encontrar problemas, mas em encontrá-los cedo no ciclo de vida do desenvolvimento, quando o custo da mudança ainda é baixo
-
Implementação e iteração
- Quando houver confiança de que revisões adicionais dificilmente exigirão grandes mudanças no design, é hora de começar a implementação
- Quando o plano encontra a realidade, podem surgir falhas, requisitos não tratados e premissas que se mostram erradas, o que pode exigir mudanças no design
- Nesses casos, atualizar o Design Doc é fortemente recomendado
- Como regra prática, se o sistema projetado ainda não foi lançado, o documento deve ser atualizado sem falta
- Na prática, muitas vezes as pessoas não atualizam bem os documentos, e por outros motivos operacionais as mudanças acabam sendo separadas em novos documentos
- O resultado pode parecer menos um documento único e coerente e mais a Constituição dos Estados Unidos com emendas anexadas
- Se o documento original contiver links para esses documentos de alteração, isso ajuda muito futuros mantenedores a entender o sistema em uma espécie de arqueologia de Design Docs
-
Manutenção e aprendizado
- Quando um engenheiro do Google encontra um sistema com o qual vai trabalhar pela primeira vez, uma das primeiras perguntas frequentes é: “onde está o Design Doc?”
- Como qualquer outra documentação, Design Docs tendem a se desalinhar da realidade com o tempo, mas muitas vezes continuam sendo o ponto de entrada mais acessível para aprender o raciocínio por trás do sistema
- O autor deveria reler seu próprio Design Doc depois de 1 ou 2 anos
- Verificar o que acertou
- Verificar o que errou
- Pensar no que decidiria de forma diferente hoje
- O processo de responder a essas perguntas ajuda no crescimento como engenheiro e na melhoria da capacidade de design de software ao longo do tempo
Como decidir quando começar com um Design Doc
- Um Design Doc é uma boa maneira de ganhar clareza e formar consenso ao resolver problemas difíceis em projetos de software
- Ele pode economizar custo ao reduzir becos sem saída de programação que poderiam ter sido evitados com investigação prévia
- Ao mesmo tempo, ele também tem custo, porque exige tempo para escrita e revisão
- As perguntas a seguir podem ser consideradas
- O design de software correto é incerto, e faz sentido gastar tempo antes para ganhar confiança?
- É útil envolver engenheiros seniores na etapa de design, mesmo que eles talvez não consigam revisar toda mudança de código?
- O design de software é ambíguo ou controverso a ponto de um consenso organizacional ter valor?
- A equipe às vezes esquece de considerar privacidade, segurança, logging ou outras preocupações transversais no design?
- Há uma forte necessidade de um documento que forneça visão de alto nível sobre o design de sistemas legados dentro da organização?
- Se a resposta for “sim” para 3 ou mais dessas perguntas, é bem provável que um Design Doc seja uma boa forma de começar o próximo projeto de software
1 comentários
Comentários no Hacker News
Saí da empresa por causa da cultura de documentos de design do Google
Logo depois de entrar, escrevi um documento, em nível bem alto, sobre uma tarefa relativamente pequena que eu já tinha feito várias vezes em outras áreas de produto, e um colega me chamou de lado para dizer: “aqui não fazemos assim”
O método que propus era só uma pequena variação do método recomendado, mas me disseram para “avaliar mais formas de fazer esse trabalho”; quando perguntei por quê, responderam: “para mostrar que você considerou as opções de forma ampla”
Com certeza existe trabalho de fachada no Google, e eu gostaria de ter entrado em outro time
A cultura do Google acabou virando uma adoração cargo cult de si mesma
Algumas empresas pelas quais passei depois do Google evitavam discutir em detalhes o processo de promoção, porque tinham visto o que acontece quando as pessoas fazem micro-otimização para se encaixar nesse processo
Como todo mundo está ocupado, não dá para conversar informalmente em 1:1 com todos, e se você não fizer uma revisão adequada com as partes interessadas, há uma boa chance de aparecer gente irritada e forçar o rollback do lançamento
Nesse contexto, o documento de design é uma ferramenta de comunicação assíncrona para temas com muita informação. Se o produto der certo, daqui a 10 anos você ainda estará “conversando” por meio desse documento com pessoas que entraram depois
Já fui salvo várias vezes por um documento de design aleatório de 2010 que explicava decisões estranhas que ainda causam problemas hoje. Talvez isso não combine com times pequenos e ágeis ou com trabalhos menos complexos, mas, mesmo que tenha virado cargo cult na cultura de engenharia, em geral existe uma razão e um contexto por trás disso
Se você está projetando algo e só existe uma solução sendo considerada, então ou não há design, ou ele não foi pensado com profundidade suficiente. Opções e trade-offs são o que compõem um design
Muitas dessas pessoas são consultores externos que trabalham com a empresa há mais de 15 anos, então já existe certo padrão simplesmente porque as mesmas pessoas fazem o mesmo trabalho há muito tempo. Mesmo assim, tentam criar um espantalho do tipo “e se as pessoas não seguirem o padrão?”
No fim, os documentos de design não existem ou estão extremamente desatualizados, e a empresa continua contratando os mesmos consultores todos os anos por um custo inflado
Agora estou em um time com muitos Googlers antigos, com mais de 15 anos de casa, e os documentos de design só existem quando são necessários. Por exemplo, quando atravessam vários sistemas ou quando há muitos trade-offs e o caso é claramente complexo. Fora isso, é simplesmente algo como “escreva um CLS”
No Google, parece que os documentos de design acabam se tornando material central no pacote de promoção
Por isso, os documentos são escritos pensando mais no comitê de promoção do que nas pessoas que realmente trabalham naquele sistema, que deveriam ser os leitores originais
Sempre que entro em uma empresa nova, proponho começar a escrever documentos de design, e isso imediatamente causa uma boa impressão na gerência :)
Muitos documentos que li pareciam já ter decidido de antemão o resultado desejado e, no começo do texto, anexavam duas ou mais opções inventadas só para fazer essa decisão parecer convincente. Uma era simples demais, outra era um overengineering desnecessário, e então escolhiam a opção que parecia razoável
Como não sabem qual documento de design poderá ser usado no pacote de promoção, registram tudo, por menor que seja, como documento de design. Existe a ideia de documento de design de 1 página, mas normalmente ele cresce de uma página para várias
Até projetos de uma semana ganham documento de design, e já tive que revisar documentos de 20, 30 ou 40 páginas que, em outra empresa, teriam sido resolvidos com um único ticket no JIRA
Muita gente aprendeu que o comitê de promoção quer ver “um documento escrito só pelo autor” e, esteja isso certo ou não, essa crença torna tudo mais lento e inibe o aprendizado cruzado. Já vi engenheiros de software passarem mais de um trimestre isolados escrevendo apenas documentos de design
O ponto central de um documento de design deveria ser o design em si, mas os outros 99% são definição do problema. Já aconteceu vezes demais de, durante a revisão, melhorar a definição do problema, descartar o design e ter que reescrever a maior parte do documento
O pior é quando, ao melhorar a definição do problema, aparece uma solução simples que não exige um design complexo. O autor já investiu muito tempo naquele design complexo e, historicamente, muitos comitês também viam essa complexidade como justificativa para promoção, então há resistência à solução simples
Já vi documentos de design sem alternativa nenhuma. Eram apenas uma descrição trabalhosa do que precisava ser feito ou do que alguém queria fazer
Com o tempo, os documentos de design acabam virando uma espécie de sistema de rastreamento de bugs visto de forma borrada. Todo mundo está ocupado com seu próprio documento de design, e ninguém trabalha nos bugs. Afinal, não se consegue promoção corrigindo bugs
Dizem que, ao entrar em um time novo, basta olhar os documentos de design, mas na prática muitas vezes eles não são rastreados de forma centralizada. Em muitos times, os documentos de design não pertencem ao time nem ao projeto, e sim ao indivíduo, porque assim dá para garantir que ninguém mais contribuiu com eles — e isso também é por causa do comitê de promoção
Também há muitos documentos de design aos quais você não tem acesso, não por serem ultrassecretos, mas simplesmente porque é assim. Não é que o time tenha só dois ou três documentos de design; há uma pilha enorme para ler. Num contexto em que o ciclo de movimentação interna no Google é de cerca de 2 anos, muitos documentos simplesmente se perdem no tempo
Em outra empresa, isso seria como dizer a alguém que entrou num time novo: “Tudo o que você precisa fazer é ler todos os bugs fechados ou todas as mensagens de commit da branch principal”
Em outro lugar, provavelmente alguém me chamaria depois do almoço para passar algumas horas em frente a um quadro branco com o time definindo o problema. Os mais experientes ensinariam aos mais novos, em tempo real, como pensar esse tipo de questão, e fariam iterações rápidas
Na maioria dos casos, isso teria sido registrado no sistema de rastreamento de bugs ou, se fosse algo grande, numa wiki do projeto ou numa pasta, tornando-se propriedade de todos
Todos os problemas acima podem ser melhorados, e de fato já tentaram melhorá-los, mas a cultura muda devagar. O conceito de documento de design em si é bom, mas tem armadilhas, e a forma como muita gente no Google usa isso não é a resposta
Sinto falta de documentos de design cujo valor fosse maior que o custo
Em geral, nunca vi essa estratégia funcionar
Por outro lado, havia documentos longos voltados a dar contexto, organizando o que o time fez, está fazendo e quais são os problemas, e esses sim tendiam a ser longos e exagerados
Trabalho na empresa mencionada, mas minha experiência não foi a mesma
Há vários tipos de documentos de design, e entre eles eu não achava nenhum útil. Era raro ver um documento de design realmente útil no Google. Parecia que documentos de design existiam para engenheiros excessivamente orientados a processos
Os tipos que vi eram mais ou menos estes: o documento de design para promoção não explica o que está tentando resolver; só fala de como esse projeto é ótimo e de como vai melhorar a empresa. A conclusão lógica é que o autor deveria ser promovido
O documento de design turbo encapsulator é um texto de papo técnico cheio de termos inéditos que ninguém entende a menos que seja sênior da equipe. Às vezes eu nem tinha certeza de que os seniores entendiam
O documento de design de recém-formado não tem conteúdo, mas é feito para ficar o mais longo possível, como se alguém que acabou de sair da faculdade estivesse tentando provar alguma coisa. Não transmite informação e muitas vezes preenche umas 70 páginas com grandes blocos de código já escrito copiados e colados
O documento de design com fatos inventados é cheio de “todo mundo sabe” e “todo mundo diz isso”. Não é tão descarado quanto um político, mas empurra o próprio design com frases como “isso segue boas práticas” ou “este software é lento, portanto...”. Falta dizer quem definiu essas boas práticas, por que são boas, o que exatamente está lento, se isso foi medido ou se é só a percepção do usuário final
99% dos documentos de design que vi eram assim. Existem exceções, mas na minha experiência são muito raras. Surpreende que o autor esteja defendendo tanto essa prática. Por outro lado, ele era diretor, não engenheiro, então talvez nesse cargo documentos de design façam sentido, embora eu ainda não saiba que valor esse tipo de gente traz
[1] https://en.wikipedia.org/wiki/Turbo_encabulator
Algo que notei cedo foi que documentos de design mantidos no Google Docs tendiam a ter qualidade inferior aos que ficavam no repositório com controle de versão. Não sei se isso era um indicador indireto da época em que foram escritos ou se o processo de code review era mais rigoroso do que a edição no Docs
Quando escrevi um documento de design grande, talvez de umas 40 páginas, fiz do jeito tradicional, em HTML escrito à mão, e ele passou pelo sistema de code review. Também foi publicado na lista de e-mail central e no servidor web, e foi bom receber feedback do funcionário número 3. Ficava organizado por categoria em um local central, então era fácil de encontrar
Não me lembro de um único documento de design ter peso grande o bastante para ser importante em uma promoção. Promoção deveria estar relacionada ao impacto geral, não a um entregável específico. Claro, o sistema tinha grandes defeitos e decisões surpreendentemente ruins apareciam com frequência, mas não me lembro de ler documentos de design otimizados para avaliação de desempenho naquela época
Se você conseguir encontrar o site com a coleção dos primeiros documentos de design em HTML escrito à mão, recomendo dar uma olhada. Talvez fossem mais úteis quando o sistema da época ainda estava em uso ativo
Alguns documentos antigos, como o SmartASS, eram cheios de explicações detalhadas sobre as equações e os modelos de base, e ajudavam bastante a entender como funcionavam e por que aquela abordagem foi escolhida. Isso influenciou meu próprio trabalho de design depois. Eu não era diretor, era só engenheiro, e aquilo realmente ajudava
Entre os documentos de design do Chrome vinculados no site chromium.org também havia alguns que me ajudaram no passado a entender a arquitetura
Eles forçam desenvolvedores juniores a pensar na solução com antecedência e justificar decisões, além de permitir que desenvolvedores seniores validem essas decisões e deem feedback assíncrono
Dito isso, eu sempre trabalhei em startups, então nunca estive em uma organização de engenharia com mais de 30 ou 40 pessoas. Big Tech pode ser diferente, mas minha experiência foi positiva
Da mesma forma, se explicar isso a outro engenheiro demora muito tempo, nem que seja uns 30 minutos, você deveria escrever um documento para economizar tempo
Não entendo como alguém pode achar que nunca é preciso escrever documento algum
Mais tarde, ao me preparar para uma promoção, eu acabava acrescentando contexto suficiente aos documentos da categoria 2 para transformá-los na categoria 1
Documentação em geral é boa, mas essa abordagem parece ter falhas
Dizem que “antes de iniciar um projeto de programação”, o principal autor de um sistema ou aplicação de software cria um documento relativamente informal, mas o próprio design é o projeto de programação, os dois são a mesma coisa
A ideia de que dá para resolver todo o design no papel antes de fazer commit de código está errada. A abordagem de documento de design, na prática, também reconhece que é preciso escrever um pouco de código no início, mas tenta enquadrar isso rigidamente como um “protótipo para demonstrar a viabilidade do design”
A grande característica do documento de design prévio é que ele dá permissão para que as pessoas façam objeções, isto é, revisão, antes da codificação de verdade. Pela minha experiência, isso faz o documento crescer cada vez mais com pistas e discussões sem sentido sobre alternativas, e ele deixa de ser um documento de design para virar um documento de “por favor, agora me deixem construir isso”
Se há uma questão arquitetural importante que exige mudança de direção, é melhor conversar e colaborar com as pessoas certas com antecedência do que elaborar um documento de design detalhado para depois ser abatido
Se isso permanecer mais próximo da ideia de um “documento relativamente informal” e o texto for atualizado ao longo do trabalho, pode de fato ser útil. Porque assim dá para construir ao mesmo tempo um sistema funcional e uma documentação útil. Mas isso fica mais próximo de documentar como parte de um processo contínuo e colaborativo do que de um documento de design
Sou Googler. Já publiquei vários artigos, mas antigamente eu não gostava de escrever documentos de design. Há alguns anos percebi os principais benefícios que isso me traz
Isso me ajuda a tirar da cabeça a parte imediata da ideia para avançar para aspectos mais profundos e considerações mais produtivas
Os defeitos ficam mais visíveis, especialmente para mim mesmo
Fica mais fácil compartilhar ideias, sobretudo com pessoas de outros escritórios. Elas normalmente dão feedback muito bom
Isso me permite entender muito melhor o volume de trabalho necessário do que simplesmente começar a programar
Em geral, isso revela o que preciso aprender antes de codificar, sistemas adjacentes ou escolhas técnicas adequadas
Também ajuda em promoções, mas projetos bem-sucedidos são ainda melhores. Ouço com frequência que meus documentos são úteis, então parece que encontrei um caminho que funciona
Isso realmente funciona? É melhor que as alternativas? Onde está essa discussão?
Quando trabalhei na Amazon, a cultura de documentos de design era excelente. Meu emprego seguinte parecia ter importado a cultura de engenharia do Google ou a cultura geral de startups de SF, mas o processo de documentos de design parecia uma piada inútil
É um mecanismo que se encaixa numa cultura de trabalho mais ampla. Se você trabalha sozinho, é um exercício luxuoso; se está numa equipe enorme, permite aproveitar mais a especialização do time inteiro e também serve como documentação
Existem alguns modos de falha. Valorizar entregáveis acima de resultados é um desalinhamento típico. Tipo escrever um documento de 40 páginas para conseguir promoção; isso normalmente não funciona, a menos que seja um caso muito júnior em que a pessoa esteja demonstrando que consegue encadear frases mais do que fazer engenharia profunda
Também pode ser excessivo para equipes que trabalham de forma mais isolada. Outras equipes pequenas conseguem se comunicar bem o bastante apenas com issues, por exemplo no Jira, e uma sessão separada para alinhar ideias
Engenheiros também precisam ser integrados ao modo de escrever documentos de design de forma eficaz. O comentário mais votado acima, de alguém desanimado porque sua primeira tentativa não recebeu elogios imediatos, pode ser um sinal disso
Escrever sobre código é difícil, e normalmente no HN esse tipo de prática é elogiado. Se você trabalha em equipe, deve tomar cuidado quando começa a sentir que seu trabalho é sempre algo que pode ser explicado em documentos compartilháveis e nunca algo que exija reflexão mais profunda
Se um grande investidor escondesse sua identidade e trabalhasse por algumas semanas como engenheiro no Google, viraria imediatamente um investidor ativista exigindo a demissão do Sundar
A escala do potencial humano desperdiçado por causa da cultura de documentos de design do Google é quase difícil de compreender
A maior parte do desenvolvimento simplesmente segue em frente, e às vezes alguém escreve um documento às pressas só para ficar mais fácil justificar um CL
Em talvez um caso entre dez eu vejo alguém exagerando demais, mas para o engenheiro de software médio isso não é uma grande perda de tempo
Se você quisesse queimar o máximo de dinheiro possível, provavelmente desenharia a empresa exatamente assim
A cultura de documentos de design tende a empurrar todo mundo para uma camada de justificativa sobre o próprio trabalho. Uma cultura de justificativa é um padrão bastante opressivo para inovadores, mesmo quando reforçada pelos colegas como cultura
Esse sistema tende a barrar tentativas visionárias e projetos ambiciosos. Esforços que não são centrados em consenso são reprimidos, e pensar “fora das normas permitidas” leva o grupo a punir você
Esse tipo de sistema gera pensamento de grupo, e o caráter centrado na tradição de “como trabalhamos” essencialmente impõe uma situação em que trabalhar de outro modo passa a ser um risco para a carreira
No Vale do Silício há culturas empresariais de todo tipo que se apoiam em clichês embalados com os termos ‘agile’ e ‘design thinking’, e na maioria das vezes isso fica mais perto de uma institucionalização que finge ser “a forma correta”, acompanhada de elementos extras que impõem socialmente a variante de cultura de culto de engenharia a que aquele campus chegou
Conheci gente demais para contar que saiu do Google porque, apesar de ser muito confortável trabalhar lá, isso limitava a carreira; e não eram poucos
Você expressou exatamente a frustração que senti trabalhando lá. Ainda assim, eu gostaria de voltar a receber aquela remuneração
Sobre agile, eu conheci a metodologia há cerca de 20 anos, na forma de eXtreme Programming, e era completamente diferente do culto cargo de hoje chamado SCRUM ou seus imitadores
No fim, era um conjunto de princípios para dar poder criativo aos desenvolvedores, impedir que gerentes interferissem no método e permitir que o trabalho fosse feito. Em troca, dava ao cliente o direito de dizer o quê, quando e em que medida algo deveria ser feito
Os próprios desenvolvedores faziam as estimativas, e o princípio era “não construir o que não será necessário”. Não havia grande design antecipado; refatoração e testes, arquitetura e design não eram stories ou tarefas separadas, mas parte do overhead contínuo como práticas padrão e recomendadas
A reunião de planejamento era colegas se alinhando numa sala, e as stories eram expressas com o mínimo de termos não técnicos em post-its num quadro branco. O stand-up era literalmente pessoas em pé em círculo dando atualizações bem curtas, apenas o suficiente para que os outros pudessem se interessar, e não um ritual para provar que apareceram no trabalho ou para se exibir
Nesse sistema, o design é uma propriedade emergente de um grupo criativo de especialistas trabalhando junto. Isso não exclui documentos de design, e discussões de arquitetura continuam existindo, mas não exige um processo explícito de PRD/documento de design
Eu queria voltar a trabalhar num lugar assim. O Google era o oposto, e tudo demorava demais
Esse comportamento falso de “somos muito inteligentes” também é uma forma de trabalho inútil. A empresa deveria se concentrar em produtos que realmente funcionam e se avaliar por isso
Outro Googler
Já há muitos bons comentários dizendo que os documentos de design do Google não são úteis, mas quero acrescentar mais uma perspectiva sobre por que isso parece um problema
Documentos de design, como foi mencionado, servem como material para promoção, então acabam gerando uma enorme quantidade de enchimento. Mas também podem parecer um substituto para a documentação real
Todo documento de design fica quase obsoleto no momento em que é concluído, mas, em vez de escrever documentação nova, as equipes apontam para esse documento de design. Como resultado, a documentação do Google é bem ruim e desatualizada
Sinceramente, teria sido muito melhor se material para promoção fosse escrever um guia de uso de 2 páginas explicando como usar algo que realmente existe, em vez de escrever 20 páginas sobre “algo que não foi feito”
Dá para ver documentos reais? Os documentos do processo de design de software parecem ser o segredo mais bem guardado de todos. Nunca vi documentos reais que pudessem ser usados em um estudo de caso
Kubernetes: https://github.com/kubernetes/enhancements/tree/master/keps
Exemplo: https://rfd.shared.oxide.computer/rfd/0177
Índice principal: https://rfd.shared.oxide.computer