ADR: documentação baseada em decisões

7 min readMar 13, 2020

Eu não sei você, mas eu sempre tive dificuldade em completar a parte de documentar qualquer coisa que desenvolvi na vida. Eu sempre tinha (ou achava que tinha) um motivo para não cumprir esse requisito.

Alguns dos meus “motivos”:

a próxima tarefa que viria era prioridade;
essa parte de documentar não foi planejada;
problemas maiores que a documentação surgiam ao longo do dia;
falta de vontade, porque o que foi feito já foi feito, não vou trabalhar nisso de novo (ah, inocente)

Vou começar uma pequena história aqui então

Existia uma equipe que era formada por mim e os outras pessoas que já trabalhavam comigo há algum tempo em outros projetos. A gente já tinha entrosamento e então chegou um projeto novo que nós conseguimos entregar a primeira versão de um MVP validado.

Até aí tudo bem né? Eram poucos serviços, porque era um projeto novo, o time já trabalhava junto há tempos em outros projetos, todo mundo se conhecia.

Como diria um amigo meu: será que está tudo bem mesmo? Com certeza não!

Alguns dos problemas que começaram a surgir:

os poucos serviços se transformaram em muitos;
80% das pessoas foram pra outros times ou saíram da empresa;
eu saí da empresa;
engenheiros novos chegaram (isso é bom, o problema é: quem iria compartilhar esse conhecimento todo?)

Com algumas a ajuda de bibliotecas que geram documentações tipo JSDocs aplicando um template bonitão, comentários por cima dos métodos de forma estruturada, Typescript e coisas assim a vida foi melhorando e eles passaram a documentar pelo menos a parte mais técnica da coisa.

Então legal, agora está tudo bem! Mesmo que pessoas saiam e os projetos cresçam, todos os métodos estão documentados, quem tiver qualquer dúvida, seja um novo engenheiro ou alguém que queira saber mais sobre os projetos poderão ler as documentações que serão geradas com um comando dentro do CI.

Pergunto de novo: será que está tudo bem mesmo? Com certeza ainda não!

A equipe continuou mudando, algo muito natural no dia a dia das empresas de tecnologia.

Um belo dia o Product Owner do time saiu da empresa. Passaram-se algumas semanas, dois novos engenheiros chegaram, porque eles já estavam no processo antes mesmo do P.O. avisar que iria sair.

Um dia depois dos novos engenheiros chegarem, o Tech Lead do time — que até então era a pessoa que mais sabia sobre a parte de produto no momento— partiu para a Europa viver seu sonho de trabalhar em uma empresa estrangeira.

Os novos engenheiros tinham mutias perguntas, porque não entendiam alguns “por ques”:

por que esse serviço foi criado?
por que foram escolhidos esses frameworks?
por que foi tomada essa decisão sobre essa regra de negócio?

O engenheiro mais antigo ficou muito atarefado. Esse novo produto foi para sua primeira minor em produção após o lançamento da primeira versão e aconteceram alguns problemas e afins. Ele só conseguia parar 30 minutos do dia para explicar e fazer onboarding dos novos colegas.

Alguns dias mais passaram e ninguém de produto chegou para complementar o time, e não tinha nenhum outro P.O. que poderia liberar tempo dele para entender o produto do seu antigo colega e passar essa informação para o restante do time.

Resultado: o time no geral levou semanas para consolidar e entender as informações. Demorou para entender o produto em sí e também várias decisões que foram tomadas ao longo dessa primeira versão. Só depois de todo esse tempo conseguiram dar continuidade aos trabalhos. Só foi menos pior, porque pelo menos tinha um JSDoc para não deixar totalmente no escuro.

Como contornar essa situação então?

Existe uma forma de evitar toda essa demora para entender os “por ques” de cada coisa.

Além das documentações de código que conhecemos, existem outros tipos de documentação.

Uma delas é a chamada “Architecture Decision Record”, ou “ADR”, ou em minha tradução “Documentação Baseada em Decisões” (porque eu acho que esse formato vale muito mais que apenas documentar arquitetura).

Uma documentação baseada em decisões é um documento que captura uma importante decisão […] tomada junto com seu contexto e consequências.

Decisões, contextos e consequências

Mais detalhadamente, cada tomada de decisão que o time faz e que considere importante deve ser documentado com base em uma decisão, em cima de um contexto e dizendo quais são as consequências da tal decisão.

Vou mostrar um exemplo na prática. Quando comecei a usar esse padrão, a primeira documentação do meu time foi justamente o porque queremos usar o ADR:

1. Documentação Baseada em Decisões

Data: 18/02/2020

Status

18/02/2020 Aceito

Contexto

O projeto necessita de alguns tipos de documentação.

DecisãoO time decidiu usar o ADR para criar um histórico fácil e rápido de ler sobre esse serviço. Com o objetivo de qualquer pessoa que queira conhecer a vida do projeto entenda lendo os próximos registros.

ConsequênciasTodos os registros serão montados utilizando a biblioteca de ADR para NodeJS feita pelo phodal. Nossa documentação será baseada em decisões, contextos e consequências.

Explicar a decisão, o contexto e as consequências sobre o ADR no início é uma boa prática do próprio ADR.

Você também pode compartilhar meu artigo com seu amigo como boa prática! :D

Com o tempo o histórico vai sendo criado

Quando novas pessoas chegarem ao time, provavelmente já existirá um histórico e você só pede para a pessoa ler tudo ou de um número X até um número Y.

Essa documentação extermina todo tipo de dúvida? Claro que não, mas ela já proporciona um bom contexto geral, talvez existam questionamentos pontuais, o que é muito melhor do que utilizar muito tempo explicando todo o ecossistema das coisas.

Implementando o ADR com NodeJS

Eu com certeza não faria esse artigo todo explicando esse conceito sensacional e deixaria você na mão sem nenhum tipo de plugin para integração né? Lembrando que sou um cara do Javascript ❤

Então pesquisando um pouco depois de descobrir essa prática, eu achei uma biblioteca muito completa feita pelo phodal e traduzida para o português por este que vos escreve.

Com poucos comandos você configura seu projeto na pasta que quiser e ele vai criando markdowns com numeração automática para você.

Vamos de passo a passo

Vamos instalar o pacote globalmente ouem modo de desenvolvimento para usar via npx no seu projeto (eu prefiro a segunda maneira e vou escrever os exemplos dessa forma):

npm install adr --save-dev

Então execute o comando inicializador:

npx adr init 'pt-br'

Após inicializado ele irá criar um JSON na raiz do projeto chamado .adr.json. Normalmente eu configuro ele para uma pasta específica onde quero guardar todas as minhas documentações, desse jeito:

{"language": "pt-br", "path":"docs/adr/", "prefix":"", "digits": 4}

Uma rápida explicação sobre cada propriedade:

language: o idioma escolhido;
path: onde você quer que sejam salvos os documentos, começa a partir da raiz do projeto;
prefix: algum prefixo para cada registro criado;
digits: mascaramento de dígitos, com o valor 4 ele fica assim: 0001, 0002.

Criando o primeiro registro

Depois de tudo configurado para criar seu primeiro registro, apenas execute:

npx adr new "Nome do seu registro"

Ele irá configurar o markdown com o template padrão vazio:

# 1. Nome do seu registroData: 2020-03-13## Status2020-03-13 proposto## ContextoAqui vem o contexto...## DecisãoAqui vem a decisão...## ConsequênciaAqui vem a consequência...

Os status que são utilizados de forma comum são: proposto, aceito ou negado.

Listando os registros

Existem algumas formas para listar todos os registros já criados. Pode ser via comando no terminal, olhando a pasta ou exportando em alguns formatos.

No terminal execute apenas:

npx adr list

Retorno do comando de listagem no terminal

Um dos formatos de exportação é em HTML. Todo o markdown já é convertido em um layout com um design bem legal de ler.

npx adr export html

Alguns comandos que montei para me ajudar

Eu abstraí alguns comandos, só pra facilitar minha vida, pode ser que facilite a sua também. Para usar é só colocar no “scripts” do package.json.

{
    "adr": "adr list",
    "adr:new": "adr new",
    "adr:update": "adr update",
    "adr:logs": "adr logs",
    "adr:generate-html": "adr export html && mv ./export.html ./docs/adr/exports/adr.html && echo \"ADR created in ./docs/adr/exports/adr.html\""
}

Essa biblioteca é muito completa e possuí muitos outros recursos bem legais. Caso você queira ver outros comandos além desses que mostrei aqui, deixo aqui o link do repositório: https://github.com/phodal/adr.

Conclusão de tudo isso

É de suma importância a prática da documentação. (EU MESMO, 2020)

Seja a pessoa que dissemina isso! Procure manter essa prática viva no seu time.

Crie uma task, uma sub-task, escreva bem grande no quadro, coloque um slide com um sinal vermelho na TV da mesa do seu time, cole post-its nos monitores de todo mundo, qualquer coisa.

Ache um jeito de documentar e fazer as pessoas documentarem tanto os métodos e classes com alguma ferramenta e também documente as decisões tomadas para gerar uma história para o seu serviço, aproveite e dê um nome bem legal para ele também.

Ser engenheiro é mais do que escrever linhas de código. É gerar experiência para outras pessoas, é resolver problemas e também se divertir fazendo isso tudo!

No médio e longo prazo muito do que o time levou algumas horas, ou até menos para escrever, vai evitar muita dor de cabeça, ajudará muita gente e mostrará como você e seus colegas são organizados.

É isso, se você gostou, ajuda com o “clap”.

Até a próxima!

Gus.

Acompanhe meu canal no YouTube: Gus Quem Fala