A cultura de escrita de Design Docs do Google (2020)

• Design docs são um dos elementos centrais da cultura de engenharia de software do Google, sendo documentos relativamente informais escritos pelo principal autor de um sistema de software ou aplicativo antes de iniciar um projeto de codificação
  • Documentam a estratégia de implementação em alto nível e as principais decisões de design, com foco especial nos trade-offs considerados nessas decisões
  • O trabalho de um engenheiro de software não é escrever código, mas resolver problemas, e textos não estruturados como um Design doc podem ser uma ferramenta de resolução de problemas mais concisa e fácil de entender do que código nas fases iniciais de um projeto

O papel dos Design docs no ciclo de vida do desenvolvimento de software

• Além da documentação original de design de software, eles também cumprem as seguintes funções:
  • Identificar questões de design cedo, quando mudanças ainda são baratas
  • Construir consenso sobre o design dentro da organização
  • Garantir a consideração de preocupações transversais (cross-cutting concerns)
  • Disseminar o conhecimento de engenheiros seniores pela organização
  • Formar a base da memória organizacional sobre decisões de design
  • Atuar como artefato de resumo no portfólio técnico do designer de software

Estrutura de um Design doc

• Como o Design doc é um documento informal sem diretrizes rígidas de conteúdo, a regra é escrevê-lo no formato mais adequado para cada projeto específico
  • Context and scope: fornece uma visão geral do contexto em que o novo sistema está sendo construído e do que de fato será construído
  • Goals and non-goals: lista os objetivos do sistema e o que não faz parte deles
  • The actual design
    • System-context-diagram: diagrama que mostra o sistema como parte de um ambiente técnico maior
    • APIs: esboço das APIs expostas pelo sistema
    • Data storage: discussão sobre como os dados serão armazenados/gerenciados
    • Code and pseudo-code: incluído apenas ao explicar novos algoritmos
    • Degree of constraint: o grau de restrição do espaço de soluções é um dos principais fatores que influenciam a forma do documento de design
  • Alternatives considered: lista designs alternativos que poderiam alcançar um resultado semelhante de forma razoável e explica os trade-offs de cada um e por que o design principal foi escolhido
  • Cross-cutting concerns: explica como preocupações comuns da organização, como segurança, privacidade e observabilidade, afetam o design

Quando escrever um Design doc

• A decisão de escrever um Design doc depende de os benefícios de consenso organizacional, documentação e revisão por seniores superarem o trabalho adicional de produzir o documento
  • Se a solução para o problema de design não for ambígua devido à complexidade do problema ou da solução, o valor de escrever o documento é pequeno
  • Um Design doc muito próximo de um manual de implementação pode ser desnecessário
  • O overhead de escrever um Design doc pode não ser adequado para prototipagem e iteração rápida

Ciclo de vida de um Design doc

1. Creation and rapid iteration: redação do documento e iteração rápida com colegas para chegar a uma versão estável
2. Review: compartilhado com um público mais amplo para revisão
3. Implementation and iteration: atualização do documento quando surgem mudanças de design durante a implementação
4. Maintenance and learning: serve como o ponto de entrada mais acessível para entender o sistema

Opinião do GN⁺

• Design docs são uma boa forma de obter clareza e construir consenso ao resolver os problemas mais difíceis de projetos de software complexos. Eles podem reduzir custos ao evitar codificação desnecessária por meio de investigação prévia, mas também geram custo porque exigem tempo para escrita e revisão
• Portanto, é preciso decidir com sabedoria se vale a pena escrever um Design doc de acordo com o projeto. Vale considerar sua criação quando houver incerteza sobre o design de software, quando a participação antecipada de engenheiros seniores puder ajudar, quando for necessário consenso organizacional sobre o design, quando a equipe frequentemente deixar passar preocupações comuns como segurança, e quando forem necessários documentos de alto nível sobre o design de sistemas legados
• É um bom exemplo da importância da documentação no processo de design de software, especialmente por ajudar a estabelecer uma cultura de design consistente em equipes grandes. No entanto, como a carga de documentação pode fazer com que engenheiros evitem esse tipo de trabalho, parece importante definir diretrizes com nível e escopo adequados a cada contexto
• Pessoalmente, considero os Design docs muito úteis em: 1) considerar trade-offs de acordo com a complexidade do design, 2) descobrir cedo questões de design antes da implementação, 3) fornecer uma visão geral do sistema para aprendizado rápido de novos membros. Ainda assim, é preciso tomar cuidado para que não se tornem documentos excessivamente formais ou distantes da implementação real
• Uma abordagem possível é tornar obrigatórios os Design docs apenas no início do projeto ou em etapas de design mais complexas, ao mesmo tempo oferecendo incentivos para que engenheiros os escrevam voluntariamente. Também pode ser útil enfatizar que a documentação ajuda a fortalecer o portfólio técnico de cada engenheiro

[GN⁺]

Comentários do Hacker News

Várias opiniões sobre a cultura de documentos de design do Google:

• Escrever documentos de design acabou virando algo voltado para promoção, então há uma tendência de serem escritos pensando mais no comitê de promoção do que em quem realmente constrói o sistema
• Tipos de documentos de design:
  • Documento de design para promoção: enfatiza o quão grandiosos são o projeto e a empresa, mais do que o objetivo do projeto
  • Documento de design do turbo encapsulador: cheio de jargões difíceis de entender
  • Documento de design de funcionário recém-contratado: muito volume, mas sem conteúdo
  • Documento de design cheio de fatos sem fundamento: usa fatos que "todo mundo sabe" como base, mas que na realidade não foram verificados
• Como o design faz parte de um projeto de programação, planejar tudo em documento antes de codificar é uma abordagem equivocada
• Escrever documentação antecipadamente só dá margem para críticas pequenas; é melhor resolver os problemas importantes com comunicação prévia entre as pessoas envolvidas
• É mais útil atualizar os documentos continuamente de forma colaborativa
• A quantidade de mão de obra desperdiçada em documentos de design é enorme
• A cultura de documentos de design da Amazon era excelente, mas em outras empresas que adotaram a cultura ao estilo Google isso não fez sentido
• Houve casos em que o projeto foi tocado sem aprovação e, mesmo assim, feedback sobre o documento de design chegou tarde demais
• Há o problema de que os documentos de design acabam substituindo a documentação de fato, o que piora a qualidade da documentação
• Os documentos de design também têm vantagens: ajudam a organizar o pensamento, encontrar falhas, facilitar a comunicação e estimar a carga de trabalho