Por mais importante que seja o código, a documentação desse código é indiscutivelmente mais importante. Nenhum desenvolvedor e nenhum software existe no vácuo; a menos que outros desenvolvedores possam entender o código que você escreveu, ele perderá muito do seu impacto potencial.
Mas e as máquinas? Eles também precisam de bons documentos?
A resposta é sim e aponta para um futuro de “documentação em camadas”, um termo que vi descrito pela primeira vez por Vlad Ionescu. Como ele detalhes, documentação em camadas significa “ter um conjunto de documentação para usuários humanos e outro conjunto de documentação especificamente para treinamento LLM (modelo de linguagem grande)”. O primeiro precisa ser facilmente consumido pelas pessoas; o último precisa ser detalhado para que ferramentas como Amazon CodeWhisperer ou GitHub Copilot produzam um código cada vez melhor. É um conceito fascinante com o objetivo final de melhorar a produtividade do desenvolvedor. Então, o que precisamos para chegar lá?
A importância de ótimos documentos
Pergunte a um desenvolvedor o que ele precisa para ser produtivo e, invariavelmente, a resposta será “ótima documentação”. Na verdade, o SlashData faz essa pergunta há anos, e os documentos sempre estão no topo da lista:
Uma boa documentação ocupa consistentemente o primeiro lugar na lista de desejos dos desenvolvedores.
É claro que isto é mais fácil de dizer do que fazer. Apesar de sabermos a importância dos documentos (por exemplo, para transmitir conhecimento, como afirma o desenvolvedor Jeremy Mikkola), é invariavelmente a tarefa que os desenvolvedores de software menos desejam realizar. Como observa Kislay Verma, escrever uma boa documentação é realmente difícil e não tão divertido quanto escrever o código em si.
Bem, ficou mais difícil.
Para o desenvolvedor Jakub Kočí, “O maior problema (na redação de documentos) é a clareza”. Afinal, ele continua: “Estamos escrevendo código primeiro para humanos, não para máquinas. Fazer com que funcione é apenas metade da solução, torná-lo bem estruturado e de fácil manutenção é outra… parte muitas vezes mais difícil.” Isso pode ter sido verdade em 2022, quando Kočí disse isso pela primeira vez, mas em 2024, é indiscutivelmente tão importante que as máquinas entendam sua documentação tanto quanto os desenvolvedores, dada a ascensão de assistentes de codificação orientados por LLM, como Amazon CodeWhisperer ou GitHub Copilot.
As máquinas precisam de documentação diferente da das pessoas – mais detalhada, por exemplo.
Apresentando documentação em camadas
Como sugere Ionescu, “A documentação em camadas é algo que algumas pessoas estão experimentando como uma solução/solução alternativa para assistentes de código LLM… sendo burro porque os documentos são burros.” Algumas empresas de software estão tentando resolver isso trabalhando diretamente com parceiros para alimentar códigos de amostra, documentos, etc., diretamente no LLM. Meu empregador, MongoDB, fez isso com a AWS. Funciona, mas não é escalável. Idealmente, como desenvolvedor de software, seja você um indivíduo ou uma empresa, você deseja criar documentação que os LLMs rastrearão por conta própria.
Você também precisa garantir que os LLMs entendam seu software em um nível profundo para que possam retornar o melhor código possível quando os desenvolvedores solicitarem. Infelizmente, como lamenta Ionescu, “a maior parte da documentação do desenvolvedor (ou mesmo da documentação do usuário) geralmente é escrita para iniciantes e isso agora é um bloqueador”. Para uma pessoa, é perfeitamente apropriado fornecer inícios rápidos e exemplos básicos de código, mas alimentar uma máquina com esse tipo de dados limitados e ela “será difícil fornecer sugestões de código sérias em nível de produção”.
A ideia por trás da documentação em camadas é que “por padrão, os bots de rastreamento para LLMs (irão) obterão documentos superdetalhados e aprofundados, e os humanos (irão) obterão documentos mais amigáveis”, resume Ionescu.
Essa é a ideia. Qual é a realidade? Bem, a realidade morde, pelo menos por enquanto. Que eu saiba, ninguém fez isso com sucesso, mas não há razão para que isso não possa ser feito. Será complicado entregar documentos que satisfaçam tanto humanos quanto máquinas, mas à medida que descobrimos as metodologias, os vencedores finais serão os desenvolvedores.
Estamos muito longe de os LLMs serem capazes de cuspir código de forma eficaz e consistente o suficiente para substituir os compiladores, como argumenta Mike Loukides, da O’Reilly. Mas já vivemos em um mundo onde os LLMs podem ajudar os desenvolvedores a escrever códigos excelentes. Melhorando a documentação para desenvolvedores e os LLMs dos quais dependem cada vez mais serão cruciais para aumentar a produtividade dos desenvolvedores.
