Modelo de Design Docs

Documento elaborado pelo time antes da codificação, de um projeto ou funcionalidade. A proposta é apresentar uma visão de alto nível com ênfase nos trade-offs considerados durante a decisão.

A ideia é ser algo relativamente informal. Assim, não exige formalização excessiva, mas deve deixar claro e compartilhável as decisões.

Objetivos:

• identificação precosse de problemas;
• alcançar consenso comum do time sobre uma decisão;
• considerar preocupações transversais, por exemplo, serviços externos que impactam uma ou mais soluções;
• escalar conhecimento;
• criar uma memória organizacional em torno das decisões de design;
• artefato resumido no portfólio técnico;

Estrutura

Abaixo uma estrutura base que pode ser utilizada.

cabeçalho

Exemplo:

• Design doc: sistema de gerenciamento de tarefas
• Autores: Leandro Andrade
• Revisores: Leandro Andrade
• Data criação: 17/04/2024
• Status: proposto (rascunho, em revisão, proposto, aprovado, rejeitado)
• Tags: design docs, gerenciamento de tarefas

visão geral

Texto breve sobre o que este documento se trata e o que se espera na leitura do documento.

Exemplo:

• Apresenta a criação de um BFF para um sistema de vendas online que agora irá oferecer um aplicativo móvel.

escopo e contexto

Descreve o cenário atual o qual o sistema está inserido, motivadores da escrita e outras informações para entendimento do contexto onde o problema está inserido. Pode ter informações sobre tecnologia atual, dívidas técnicas.

O objetivo é que os leitores fiquem atualizados.

Exemplo:

• O sistema de vendas online da empresa XYZ busca aprimorar a experiência do usuário por meio do lançamento de um aplicativo móvel. No entando, a API REST to sistema possui um payload demasiadamente grande para ser processado em dispositivos móveis.

objetivos e fora de escopo

Os objetivos são requisitos de negócio ou técnicos que serão alcançados com a conclusão da atividade. Fora de escopo são pontos que não serão contemplados ou não são uma preocupação da atividade.

Podem ser descritos em formato de lista.

Exemplo:

• Objetivo:
  • reduzir tempo de resposta e melhorar a experiência do usuário;
  • melhorar a escalabilidade para atender a demanda crescente de usuários;
  • aumentar a taxa de conversão de vendas ao oferecer uma experiência de usuário mais rápida e intuitiva;
  • facilitar a manutenção e evolução do sistema de vendas online, isolando o código legado;
• Fora de escopo:
  • criação de novas funcionalidades no sistema de vendas online;
  • implementação de segurança de alto nível no BFF, o que será tratado em outro projeto específico;
  • criação de uma solução de cache, mas poderá ser implementada posteriormente;

design

Dado o contexto, objetivos, fora de escopo, mostre porque uma determinada solução atende melhor a esses objetivos. Comece com uma visão geral e entre nos detalhes.

Pode conter diagramas, API's, dados que serão manupulados e sensibilidade dos mesmos, códigos telas, payloads.

Destacar os trade-offs.

Adicionar fatos e dados para gerar valor ao design. Elementos visuais são complementares e não substitutos das explicações.

Exemplo:

• O objetivo é melhorar a experiência do usuário e a escalabilidade os sistema de vendas online existente, adicioando um BFF para fornecer respostas mais leves. Para atender esses objetivos, propomos a implementação de um BFF usando a plataforma/ferramenta X. O BFF será responsável por fornecer uma camada de abstração para as API's do backend e fornecer respostas mais rápidas para o frontend. Isso resultará em uma resposta de usuário mais rápida e intuitiva, aumentando assim a taxa de conversão de vendas.
• prós:
  • melhoria na experiência do usuário;
  • é possível criar API's específicas para cada componente;
  • redução de 30% no payload trafegado;
• contras:
  • maior complexidade na arquitetura, com a introdução de um novo componente;
  • possível aumento no custo de desenvolvimento;
  • necessidade de garantir que as API's do backend estejam preparadas para suportar a orquestração do BFF.

alternativas consideradas

Os sistemas ou soluções alternativas que foram consideradas para a resolução do problema, explicando compensações e motivações da escolha.

Dicas:

• uma alternativa a ser consideradas é não fazer nada;
• seja sucinto, mas destaque porque a solução escolhida é a melhor opção;

Exemplo:

• utilização de headers HTTP:
  • Uma dessas restrições seria o uso de headers HTTP para restringir o conteúdo da resposta enviada pela API. Sua implementação e manutenção é prejudicada pois alterações futuras seriam complexas.
• compressão de dados:
  • Usar técnicas de compressão de dados. No entanto, essa solução não se mostrou eficaz já que reduziu apenas 10% o tamanho do payload.

preocupações transversais

Descrever o que pode impactar outras pessoas. Pode ser uma preocupação de segurança, quebra de compatibilidade, aumento de fluxos em outros sistemas.

Envolva os times impactados o mais cedo possível e peça revisões ao times.

Exemplo:

• É importante garantir que o BFF seja projeto e implementado de forma segura. É necessário garantir compatibilidade dos backends com o BFF, para que não haja problemas de integração. É importante monitorar a infraestrutura para garantir que suporte essa carga adicional e que o sistema continue operando de maneira adequada.

testabilidade e observabilidade

Descreva como a solução será testada e como as métricas serão criadas para garantir o atingimento do sucesso. Inclua como a solução será observada.

plano de implantação

Segmentação das entregas e passos necessários para entrega de valor da solução. Rollout.

perguntas em aberto

Pontos que ainda não foram definidos ou ainda são desconhecidos.