Democratizando Decisões Arquiteturais com o uso de ADR’s
Conceitos-chave (TL; DR)
- O Manifesto Ágil trata de Agilidade e Documentação, agilidade prevê que a documentação é uma parte importante no ciclo de desenvolvimento de software e quando não aderimos a esse princípio, encontramos anti-patterns de documentação.
- ADR significa Registro de Decisão Arquitetural, provendo uma abordagem lightweight para a documentação de projetos com capacidades para automação, cocriação e democratização de decisão de arquitetura e negócios por toda a companhia.
- As ADR’s são estruturadas de forma simples, em seções contendo Título, Contexto, Decisão, Status e Consequências.
- Na Livelo, usamos ADR’s para a cocriação e democratização de decisões de arquitetura, promovendo as escolhas dos times de engenharia, gerando engajamento e cultura de dono.
Anti-patterns
Muitas vezes negligenciada, a documentação de projetos, tem sido cada vez mais uma prática que impacta a qualidade de projetos, sobretudo aqueles com curto tempo de desenvolvimento (time-to-market) e alta rotatividade de pessoas.
A Engenharia de Software e Agilidade não se opõe à documentação, mas reforça em seus valores e princípios que a documentação deve envolver práticas rápidas, modulares, simples e que possam se manter atualizadas ao longo do ciclo de vida do software.
Exemplos de decisões que devem ser registradas e acompanhar esse ciclo são — motivo e racional (trade-offs) relacionados ao uso de uma determinada tecnologia, protocolo ou uso de componentes de software como microsserviços ou ferramentas de mercado.
Uma documentação não aderente, ausente ou sem rastreabilidade pode levar a anti-patterns de documentação, tais como:
- Nenhuma decisão é feita, somando a isso o receio em realizar uma escolha incorreta ou decisão errada;
- Decisão é feita sem qualquer justificativa, e as pessoas não compreendem o porquê da motivação/escolha. Isso leva a várias discussões recorrentes sobre o tema;
- A decisão não é capturada como um modelo arquitetural em um repositório para futura rastreabilidade, racional relacionado com a decisão e compreensão compartilhada.
Para suprir essas dificuldades, as ADR’s são uma abordagem viável e efetiva na documentação de projetos ágeis, especialmente voltados para aspectos de cocriação e a democratização da solução e decisão de arquitetura por toda a companhia.
Aqui na Livelo, usamos ADR’s com diferentes propósitos, dentre eles vale citar:
- Habilidade para cocriação e democratização de decisões de arquitetura;
- Suporte à documentação dinâmica e mais próxima dos desenvolvedores;
- Decisões horizontais promovendo melhores práticas e engajamento.
Architectural Decision Records (ADR’s)
ADR’s têm se tornado uma das maneiras efetivas de documentação de decisões arquiteturais. Popularizadas e difundidas por Michael Nygard em seu blog pessoal, as ADR’s atualmente tem sido utilizadas e recomendadas para documentação pela AWS, Google e até mesmo para capturar decisões relacionadas a projetos de UX e Design System.
Segundo Michael Nygard, as ADR’s promovem maior visibilidade, colaboração e cocriação sobre decisões de arquitetura de software, especialmente para novas pessoas que chegam ao projeto.
Como exemplo, vamos explorar um cenário de anti-patterns de documentação e como as ADR’s podem ser usadas para suprir as dificuldades e impactos negativos desse cenário.
Um novo desenvolvedor (que acabou de chegar na empresa) pode ficar perplexo ao se deparar com uma decisão do passado que usa o protocolo LDAP para integração multi-tenant. Nesse caso, o desenvolvedor tem duas opções, primeiro o desenvolvedor pode aceitar a decisão cegamente ou então, ele pode decidir mudar a forma de integração de forma proposital considerando que uma nova abordagem e tecnologia é mais viável. No final, o desenvolvedor opta por modificar a forma de integração para um protocolo mais moderno e robusto. Essa nova integração funcionou para 90% dos casos, mas gerou impactos no acesso de outros portais internos. Em uma avaliação de troubleshooting com o time de SRE foi identificado que um parâmetro de configuração só é possível via o protocolo antigo (modo LDAP). Como resultado, a feature toda que levou 3 meses para ser desenvolvida teve que sofrer um rollback emergencial pois a complexidade de implementação era inviável.
Esse cenário tem vários impactos negativos, técnicos, custo e até mesmo relacionados a pessoas, como por exemplo, falta de engajamento do time para evoluir o modo de integração, medo e insegurança.
Nesse contexto, para evitar e suprir essas dificuldades, usamos um conjunto de registros de decisões "arquiteturalmente significantes" que influenciam e sensibilizam estruturas, componentes, fatores de qualidade e técnicas de construção de software.
Portanto, é nesse cenário do exemplo anterior que as ADR’s são utilizadas, sobretudo, para reduzir os efeitos negativos decorrentes da ausência de documentação em projetos ágeis.
Vejamos a seguir, as principais definições relacionadas com ADR’s.
Uma Decisão Arquitetural — Architectural Decision (AD) é uma decisão justificável de software que endereça requisitos funcionais e não funcionais arquiteturalmente significantes.
Uma Decisão Arquitetural Significativa — Architecturally Significant Requirement (ASR) é um requisito que tem uma medida e afeta a qualidade e arquitetura de software.
Um Registro de Decisão Arquitetural (ADR) é um arquivo texto lightweight (simples e leve) que permite o compartilhamento e balanceamento entre forças positivas e negativas de uma única AD (Architectural Decision).
Coleção de ADR’s e Logs de decisão (decision log) são grupos e coleções de ADR’s organizadas e mantidas dentro de um projeto e se referem às decisões e racionais do projeto.
Architectural Knowledge Management (AKM) consiste em toda a coleção de ADR’s e outras decisões que fornecem governança, taxonomia e linguagem ubíqua dentro da organização.
Estrutura Básica
Uma ADR deve conter uma estrutura básica, simples e leve de ser escrita e lida. As principais seções de uma ADR são:
- Título — nomes curtos e semânticos para facilitar a sua localização.
- Contexto — linguagem neutra que descreve as forças tecnológicas, politicas, negócios e outros fatores que levaram a tal decisão. Descreve um conjunto de fatos ordenados que caracterizam o problema.
- Decisão — linguagem em voz ativa que indica a decisão tomada sobre as forças indicadas no contexto.
- Status — indicadores de status como "Proposta" e/ou "Em revisão".
- Consequências — conjunto de fatores positivos e negativos que influenciam a decisão indicada.
Exemplo de ADR
ADR-042-Uso de HTTP/2 e gRPC para comunicação bidirecional e streaming de dados
Status: [em revisão]
Decisores: [Time de Arquitetura e Engenharia]
Contexto
A comunicação bidirecional entre cliente e servidor é uma abordagem de desenvolvimento de software que pode envolver opções diferentes como o uso de WebSocket ou HTTP/2 com suporte a gRPC.
Decisão
Nós optamos pela opção HTTP/2 com suporte a gRPC por ser uma abordagem evolutiva, bidirecional e com capacidade de negócios para envio de quadros binários e simples (proto-buf) e capacidade de uso em paralelo.
Consequências
- Bom, porque é uma abordagem evolutiva.
- Bom, porque representa uma melhora na performance de comunicação entre aplicação cliente e servidor.
- Bom, porque possibilita capacitar e motivar talentos para uso de novas abordagens de tecnologia.
- Bom, porque é indicado para comunicação entre componentes de backend e aplicativos Mobile que fornecem suporte.
- Ruim, pois possui capacidade limitada para certos tipos de browsers e navegadores.
Conclusão
Esse artigo teve como objeto apresentar uma visão geral e definições importantes sobre ADR’s. Também foi apresentado os principais anti-patterns encontrados quando a documentação de software é negligenciada de alguma forma.
Em um próximo artigo, falaremos sobre o processo de revisão das ADR’s e como organizar ADR’s em repositórios.
