Pra mim, documentação escrita fora do momento em que é útil envelhece mais rápido do que o código que descreve. Em times que mantêm páginas extensas de wiki, o que se vê é o conteúdo crescendo, perdendo sincronia com o sistema real em semanas e passando a competir com o próprio código pela posição de fonte de verdade. O engenheiro que consulta a página encontra informação parcialmente correta, que gera decisão parcialmente correta, e o custo dessa imprecisão se acumula até que alguém abra o código pra verificar e descubra que metade da página está obsoleta. A documentação deixa de ser ativo e passa a ser passivo operacional, mantida por inércia e consultada com desconfiança.
Equipes costumam responder ao problema de duas formas igualmente ineficazes. A primeira é institucionalizar a escrita antecipada, exigindo especificação detalhada antes de cada implementação, o que produz documento que descreve o sistema como ele foi planejado e não como ele existe. A segunda é abandonar a documentação por completo, confiando que o código é auto-explicativo, o que funciona enquanto o autor original está disponível e falha no primeiro onboarding. Entre esses dois extremos, o modelo just-in-time propõe uma tese descritiva diferente: documentação tem valor apenas quando existe leitor identificável, pergunta concreta e janela temporal em que a resposta é necessária. Fora dessas três condições, escrever documentação é produzir conteúdo sem demanda, e conteúdo sem demanda degrada.
Na minha análise, o ponto de entrada é onde a leitura efetivamente ocorre. O engenheiro que tenta entender um sistema raramente lê um documento do início ao fim. Ele chega a um trecho específico dentro do editor ou do repositório, tentando responder uma pergunta que surgiu no meio de uma tarefa. A probabilidade de a resposta ser encontrada é função direta de três variáveis: proximidade física entre documentação e código, granularidade da unidade documentada e frescor da última atualização.
Um README de 12 linhas no diretório do módulo, atualizado junto com a última mudança significativa, é consultado e confiável. Uma página de Confluence com 47 seções, escrita há oito meses e indexada por busca que retorna resultados desatualizados, é ignorada mesmo quando contém a resposta correta. Documentação não encontrada no momento da pergunta equivale a documentação que não existe, e o modelo just-in-time trata essa equivalência como ponto de partida.
A escrita no momento da pergunta exige um gatilho claro. O mais previsível é o onboarding, até porque produz perguntas concretas em sequência, e cada pergunta não respondida é indicador preciso de lacuna documental. Toda pergunta feita por um novo integrante que não tenha resposta num README próximo ao código é candidata à documentação, e a resposta dada num canal de mensagem deve migrar pro repositório no mesmo dia. O segundo gatilho é a decisão arquitetural não trivial, capturada como ADR no próprio repositório, cuja ausência se manifesta como decisão repetida meses depois com raciocínio perdido (Architectural Decision Records). O terceiro é o incidente, que produz contexto que se perde em dias se não for escrito enquanto a memória está fresca.
O trade-off aparece no custo de manutenção. Documentação próxima ao código, versionada com ele e revisada no mesmo pull request, tem custo de manutenção embutido no fluxo de desenvolvimento e se mantém viva enquanto o código for tocado. Documentação distante, em sistema separado, exige disciplina de sincronização que nenhuma equipe mantém consistentemente, e o decaimento é inevitável. O ganho do modelo just-in-time é obtido ao aceitar que documentação longe do código vai morrer, e ao mover o conteúdo crítico pra onde ele pode viver. O custo é aceitar que certos tipos de documento, sobretudo os que cruzam múltiplos repositórios ou descrevem sistemas agregados, não cabem nesse modelo e precisam de outro mecanismo de manutenção, com dono explícito e revisão periódica agendada.
Numa situação recente que acompanhei, uma equipe arquivou uma wiki de 120 páginas após descobrir que apenas 14 haviam sido acessadas nos últimos seis meses. O conteúdo das 14 páginas ativas foi redistribuído entre READMEs de módulo, ADRs e runbooks próximos ao código, com uma única página permanecendo num sistema centralizado por descrever integração entre três times. As 106 páginas restantes foram arquivadas sem substituição, e nas 12 semanas seguintes nenhuma foi solicitada de volta. O efeito foi redução do tempo médio de resposta no onboarding e eliminação do hábito de consultar a wiki como primeira etapa, substituído pela busca direta no repositório.
Na minha avaliação, documentação escrita just-in-time tende a ser melhor escrita. Quando existe leitor concreto e pergunta concreta, o texto converge pro mínimo necessário, até porque o autor sabe o que o leitor precisa saber e o que ele já sabe. Documentação escrita antecipadamente tende ao excesso, já que o autor tenta cobrir todos os leitores possíveis, e o resultado é um texto que serve mal a todos. A restrição temporal funciona como critério de edição: o que não for necessário agora provavelmente não é necessário.
A quantidade de documentação de um sistema funciona com frequência como indicador inverso de qualidade. Times que escrevem pouco e mantêm o pouco que escrevem próximo ao código, atualizado no mesmo fluxo de commits e revisões, operam com menor dívida documental do que times que escrevem muito em sistemas paralelos. A pergunta útil recai sobre onde o próximo leitor vai procurar, e a resposta determina onde o próximo parágrafo será escrito.
Sources: