Trilha versus biblioteca

Todo time de engenharia tem a mesma história. Alguém sai, o conhecimento crítico vai embora junto, o time corre para escrever documentação. Criam um wiki. Por duas semanas as pessoas contribuem. Depois apodrece. Seis meses depois o wiki é um cemitério de páginas desatualizadas em que ninguém confia.

O problema nunca foi registrar. Foi encontrar.

Existem duas abordagens fundamentalmente diferentes para o conhecimento de uma organização. Uma piora com o tempo, a outra melhora. A maioria dos times investe na errada.

01O modelo da biblioteca

A abordagem tradicional trata conhecimento como biblioteca: escreva, organize, mantenha. Páginas de wiki. Bases de notas. Registros de decisão de arquitetura. Guias de integração. Documentos de "como fazemos as coisas".

O modelo da biblioteca parece certo. Parece responsável. E está condenado.

A biblioteca falha porque é uma atividade de segunda ordem. Ela fica fora do trabalho, é escrita depois do fato e se mantém por uma disciplina que se desgasta. Ninguém acorda animado para atualizar o wiki, e a documentação está sempre uma refatoração atrás da realidade.

A biblioteca apodrece porque mantê-la não é o trabalho de verdade de ninguém. E no instante em que vira o trabalho de alguém, essa pessoa deixa de fazer o trabalho que gera o conhecimento que valeria a pena registrar.

02O modelo da trilha

A trilha inverte tudo. Em vez de construir uma base de conhecimento separada, você trata os artefatos primários do trabalho como a própria base.

Mensagem de commit. Descrição de pull request. Comentário de revisão. Conversa ligada ao chamado. Discussão de decisão de projeto. Análise de incidente registrada nos chamados. Isso não é insumo para uma base de conhecimento. Isso é a base de conhecimento.

O "porquê" de cada decisão já estava sendo registrado - em descrição de PR, mensagem de commit, discussão de revisão. O conhecimento sempre esteve lá. O problema é que nenhum ser humano conseguia vasculhar três anos de comentário para achar o que explicava por que o middleware de autenticação funciona daquele jeito.

A IA consegue. Na hora.

03Como isso fica na prática

Mesma pergunta, duas abordagens, resultados bem diferentes.

Ninguém precisou escrever um documento. Bastou explicar o próprio raciocínio enquanto fazia o trabalho.

O trabalho era a documentação. Sempre foi.

04Onde a trilha quebra

A trilha não é perfeita. Ela tem uma fraqueza crítica: as passagens de bastão. Dentro de cada fase do trabalho - conversa com cliente, arquitetura, desenvolvimento, operação - a trilha é rica. O conhecimento falha justamente nessas passagens.

O "porque" não atravessou a fronteira. Dois anos depois alguém pergunta por quê, e ninguém lembra.

Cada uma dessas leva trinta segundos. Nenhuma delas é documentação. É apenas fazer o trabalho com um pouco mais de deliberação.

05Por que a trilha melhora com o tempo

A assimetria central é esta. A biblioteca piora com o tempo porque apodrece. A trilha melhora com o tempo porque a busca melhora.

Uma descrição de PR escrita em 2022 é tão exata hoje quanto no dia em que foi escrita. Ela descreveu uma mudança específica num momento específico. Não tem como ficar desatualizada, porque nunca pretendeu descrever o presente - descreveu um instante. O código pode ter mudado; o raciocínio é permanente.

Depois que os artefatos estão ligados - email do cliente à conversa, à tarefa, ao PR, ao comentário de revisão, ao commit - eles formam um grafo navegável. Não é preciso biblioteca curada para percorrer: a resposta é reconstruída da fonte toda vez.

A biblioteca exige investimento contínuo só para não piorar. A trilha não exige nada e se acumula.

06O conhecimento de uma pessoa contra a trilha de todo mundo

Quem opera sozinho carrega o conhecimento de uma pessoa: os vieses dela, os pontos cegos dela, a experiência dela. Quando essa pessoa sai, leva tudo.

Um time com trilha rica carrega as decisões de muita gente - perspectivas diferentes, cicatrizes diferentes, julgamento diferente aplicado ao longo de anos. Uma IA com acesso a essa trilha reconstrói o raciocínio coletivo de todo mundo que já contribuiu, não a visão de uma pessoa só.

Quem entra no time não precisa mais de meses para absorver conhecimento tribal. A pessoa pergunta, a trilha é encontrada, e em minutos ela entende não só o que o sistema faz, mas por que faz assim, quem decidiu e que restrição moldou a escolha.

07Pare de documentar. Comece a explicar.

As ações são pequenas. São de graça. E se acumulam para sempre.

Nada disso parece documentação. É justamente esse o ponto. No instante em que você separa o registro do conhecimento do trabalho, cria uma atividade de segunda ordem que uma hora vai ser abandonada.

O trabalho é a documentação. Deixe o trabalho mais rico e deixe a IA fazer a busca.