Na Salvy estamos em constante movimento, sempre pensando em novas formas de entregar valor para nossos usuários com qualidade e segurança. Para isso, é essencial que a arquitetura de nossos sistemas esteja bem documentada e que as decisões tomadas ao longo do tempo sejam claras e bem compreendidas por todos os membros da equipe. Com essa finalidade, utilizamos a técnica de Architectural Decision Records (ADRs).
O que são ADRs?
ADRs são uma forma de documentar as decisões arquiteturais tomadas ao longo do desenvolvimento de um sistema. Consistem em documentos sucintos que descrevem como novas funcionalidades serão implementadas, e o porquê de serem feitas da forma que está sendo apresentada.
Aqui vale tudo que os autores do ADR considerarem importante para contextualizar seus leitores: regras de negócio, limitações do sistema ou de provedores terceirizados, insumos de outros times, schemas de bancos de dados, endpoints que serão implementados, considerações de performance ou segurança, etc. Você pode conferir o template do Notion que usamos como base para nossos ADRs aqui.
ADRs como guia de projeto
Os ADRs também tem outro papel muito importante para nós: o de fomentar discussões antes de sairmos botando a mão na massa. Nossos ADRs são construídos de forma colaborativa e multidisciplinar. Primeiro, um dos membros do nosso time de engenharia escreve uma versão inicial do documento, partindo do nosso template no Notion. Em seguida, envia para o resto do time revisar, e, se julgar necessário, para os times de produto e design.
Os revisores fazem comentários para sanar dúvidas e propor alterações em cima da solução proposta. Realizamos algumas iterações desse processo até que os envolvidos dêem sua aprovação para o documento. A partir desse momento, partimos para a implementação da funcionlidade documentada. Esse processo todo pode ocorrer de forma assíncrona, mas tivemos resultados ainda melhores quando realizamos uma reunião síncrona após a revisão inicial para finalizar o ADR.
Realizar essa etapa de projeto primeiro reduz bastante a carga cognitiva no momento da implementação, e faz maravilhas para a qualidade do código produzido ;)
Como escrevemos ADRs na Salvy
Vamos passar pelo passo a passo do template que disponibilizamos acima para explicar como escrevemos nossos ADRs. Somos grandes fãs do Notion aqui na Salvy, mas você pode usar a ferramenta que preferir para escrever os seus ADRs. Se você quiser usar nosso template, recomendamos que customize ele para melhor atender as necessidades do seu tempo, e dê preferências a ferramentas que possibilitem alguma forma de edição colaborativa.
Contexto e declaração do problema
Nessa sessão, descrevemos em poucas frases o problema que estamos tentando resolver. É importante focar na necessidade do produto aqui e não se estender muito. Um ou dois parágrafos curtos costumam ser suficientes. Além da descrição do problema, você pode incluir o que motivou a necessidade de resolvê-lo (ex.: feedback de um cliente, roadmap de produto, oportunidade de negócio).
Direcionadores de decisão
Aqui listamos fatores chaves que devemos considerar na concepção da solução. Isso inclui tanto necessidades negociais e de produto, quanto pontos técnicos, como idempotência, orquestração, potenciais vulnerabilidades, etc. É importante que os pontos listados sejam claros e concisos para que guiem os engenheiros no momento da implementação.
Fora de escopo
É costume também especificarmos o que estará fora do escopo do ADR. Essa limitação exerce um papel fundamental em garantir que a solução proposta caberá no tempo que pretendemos dedicar à funcionalidade que estamos projetando, e que não vamos tentar abraçar o mundo de uma só vez.
Proposta(s) de solução
Essa é a parte da ADR onde as sessões anteriores convergem e resultam em uma ou mais propostas de solução técnica para o problema em discussão. Novas tabelas e endpoints, eventos, comunicações assíncronas, orquestrações entre sistemas, alterações em módulos já existentes, integrações com provedores externos… Tudo isso e muito mais pode se espcificado nessa sessão. Usamos todos os recursos que acharmos necessários para ilustrar com clareza a solução que estamos propondo, como diagramas, listas, referências externas e trechos de pseudo-código.
Na maioria dos casos, não concebemos mais de uma proposta de solução. A proposta ainda estará sujeita a revisão e discussão, e usamos esse momento para refiná-la e chegar no que julgamos ser a melhor solução para o momento. Contudo, já passamos por situações em que não estava claro o caminho a seguir, e o autor da respectiva ADR optou por conceber duas ou três propostas diferentes, elencando as vantagens e desvantagens de cada uma. No momento da revisão, debatemos sobre qual acreditamos ser a mais adequada para o nosso momento, e chegamos a um consenso sobre qual caminho tomar. Por vezes, chegamos a fazer PoCs de cada alternativa para validar cada solução. É uma estratégia especialmente efetiva quando se lida com produtos ou provedores externos. Pensar em tantas soluções diferentes demanda tempo e trabalho, por isso optamos por fazer isso somente quando realmente é necessário.
Mermaid.js
Se você pretende usar diagramas no seus ADRs, recomendamos o Mermaid.js. É uma ferramenta bastante poderosa para fazer diagramas através de código. Claro que adoramos soluções baseadas em código, mas o mais importante: acessibilidade. Por ser baseada em texto, ela é compatível com leitores de tela. Além disso, o Notion renderiza os diagramas Mermaid sem necessidade de exportar uma imagem. Basta criar um code block, selecionar a linguagem como Mermaid e fazer o seu diagrama. Uma alternativa ao Mermaid que usamos bastante é o Excalidraw. Apesar de não ser tão acessível quanto o Mermaid, é bem fácil de usar e gera diagramas bonitos.
Roteiro de implementação
Depois que a solução estiver revisada, discutida e lapidada, precisamos determinar um roteiro para implementá-la. Geralmente deixamos essa sessão por último, já que tem uma dependência direta com a proposta de solução escolhida.
Na Salvy, usamos o Linear para gerenciar nosso trabalho, então é natural que nosso roteiro consista em quebrar a solução escolhida em tarefas e mapeá-las para o Linear. A verdade é que não tem um jeito certo de fazer isso. Como você vai escrever esse roteiro depende muito dos processos do seu time e das ferramentas que vocês utilizam.
Conclusão
Essa é a forma que a Salvy escreve seus ADRs e planeja features futuras, garantindo que a gente tenha qualidade nas nossas entregas sem sacrificar a velocidade. Fique à vontade para explorar nosso template do Notion e adaptá-lo para a sua realidade. Quaisquer dúvidas e sugestões, entrem em contato com a gente, adoramos conversar sobre esse assunto!