Seu código está documentado. Suas decisões não.

A maioria das equipes de engenharia bem administradas possui uma documentação de código razoável: comentários, READMEs, documentação de APIs, assinaturas de tipos e docstrings. O próprio código serve como uma forma de documentação do que o sistema faz. Um engenheiro competente que leia a base de código consegue entender o comportamento atual de qualquer componente.

O que eles não conseguem entender apenas pelo código é o porquê.

Por que o serviço de autenticação é um microsserviço separado em vez de um módulo no monólito? Por que o pipeline de dados usa processamento em lote em vez de streaming? Por que essa biblioteca específica é usada para requisições HTTP quando existe uma alternativa mais popular? Por que o esquema tem uma coluna chamada legacy_status que é preenchida, mas nunca lida?

Cada uma dessas perguntas tem uma resposta, e essa resposta foi discutida, debatida e decidida em algum momento no passado. A discussão provavelmente aconteceu em uma conversa no Slack, em uma reunião ou em um comentário de PR. A decisão foi tomada, o código foi escrito e o raciocínio evaporou.

O custo de decisões perdidas

Quando o raciocínio por trás de uma decisão é perdido, duas coisas acontecem.

Novos engenheiros cometem erros que a equipe já cometeu. Um engenheiro que não sabe por que o serviço de autenticação é separado do monólito pode propor a fusão deles, passar uma semana criando uma prova de conceito e depois descobrir em uma revisão que a separação existe devido a um problema de latência descoberto da maneira mais difícil há dois anos. A semana foi desperdiçada porque o raciocínio não estava documentado.

Decisões já tomadas são rediscutidas. Alguém levanta a questão de lote versus streaming para o pipeline de dados. A equipe passa uma reunião debatendo isso. Na metade do tempo, alguém lembra que isso foi discutido há um ano e a conclusão foi de que o streaming exigiria mudanças de infraestrutura que não valeriam a melhora na latência. A reunião foi desperdiçada porque a decisão anterior e seu raciocínio não eram fáceis de encontrar.

Ambos os custos são invisíveis no momento (parecem discussões normais de engenharia) e enormes no total (as mesmas decisões debatidas várias vezes, os mesmos erros repetidos por engenheiros sucessivos, o mesmo contexto reconstruído do zero sempre que alguém novo se depara com o sistema).

Como é a cara de uma documentação de decisão

Um documento de decisão não precisa ser elaborado. Os elementos essenciais são:

A questão. O que estava sendo decidido? Formulada como uma pergunta clara e pesquisável.

As opções consideradas. Quais alternativas foram discutidas? Mesmo uma lista breve é valiosa, pois mostra que a abordagem atual foi escolhida e não adotada por padrão.

A decisão. O que foi escolhido?

O raciocínio. Por que essa opção foi selecionada? Quais trade-offs foram aceitos? O que precisaria mudar para que a decisão fosse revisitada?

A data e os participantes. Quando isso foi decidido e quem estava envolvido?

Esse formato às vezes é chamado de Registro de Decisão de Arquitetura (ADR), e as equipes que o utilizam consistentemente relatam reduções significativas na rediscussão de decisões e no atrito de integração de novos membros.

O ângulo da automatização

O desafio com a documentação de decisões é o mesmo de qualquer documentação: exige que alguém a escreva, e o momento da decisão raramente é o momento em que alguém está com vontade de escrever um documento sobre isso.

Documentações autoescritas podem capturar decisões a partir das fontes onde elas realmente são tomadas. Uma conversa no Slack onde a equipe debate duas abordagens e chega a uma conclusão pode ser resumida automaticamente como um registro de decisão. Uma reunião onde as opções de arquitetura são discutidas pode gerar um documento estruturado a partir da transcrição. Uma descrição de PR que explica uma escolha de design não óbvia pode ser vinculada ao histórico de decisões mais amplo.

As decisões já estão sendo tomadas. As discussões já estão acontecendo. O que falta é a captura, e a captura automatizada a partir dos canais existentes é muito mais confiável do que pedir aos engenheiros que escrevam suas decisões após o fato.

Perguntas frequentes

Isso não é exagero para decisões pequenas? Nem toda decisão precisa de um documento formal. O limite: se você espera que um novo engenheiro pergunte "por que isso é feito dessa forma?" ao se deparar com isso, o raciocínio deve ser documentado. Decisões sobre arquitetura fundamental, escolhas de tecnologia e trade-offs significativos quase sempre se qualificam.

Onde os documentos de decisão devem ficar? Junto com a documentação do sistema, pesquisáveis e vinculados ao código ou sistema relevante. Um registro de decisões separado da wiki de engenharia é melhor do que nada, mas menos útil do que decisões integradas à documentação do sistema ao qual se referem.

Como documentamos decisões passadas retroativamente? Comece pelas decisões que causam mais atrito: aquelas que são rediscutidas com mais frequência ou sobre as quais os novos engenheiros mais perguntam. Escreva o raciocínio com a ajuda de quem se lembra dele e aceite que as decisões mais antigas talvez precisem ser marcadas como "reconstruídas" em vez de definitivas.

Leitura relacionada: O fator ônibus, O custo oculto do conhecimento tribal, Dívida de documentação. Páginas relacionadas: Documentos autoescritos, Registro de decisões, Para equipes de engenharia.