Código em contexto: como a IA pode ajudar a melhorar nossa documentação

Embora eu tenha escrito alguns plug-ins do Steampipe, eles exigiram apenas um conhecimento básico do SDK do plug-in. Certamente não sou o único que tem lutado para compreender seus mecanismos mais avançados. Em nosso hackathon anual da empresa em 2022, participei de um sprint de uma semana para melhorar a documentação do SDK, trabalhando com vários membros da equipe, incluindo o desenvolvedor líder do Steampipe (que é o autor do SDK). O exercício rendeu um ensaio divertido sobre programação alfabetizada em Go, mas os resultados não mudaram muito.

Eu li muitos códigos de plug-ins desde então e escrevi alguns, mas ainda não me sentia confiante em minha capacidade de compreender, aplicar e explicar vários padrões principais. Tenho certeza de que a assistência do LLM teria melhorado o resultado de nosso sprint de documentação de 2022. Não podemos repetir esse experimento, mas tentei novamente com a ajuda do Unblocked, uma nova ferramenta apoiada por LLM para desenvolvedores que se concentra menos em escrever código (embora também faça isso) e mais em entendê-lo. Como diz o fundador Dennis Pilarinos:

Para esse fim, o Unblocked pode não apenas ingerir seus repositórios de código, assim como o Cody da Sourcegraph, mas também material relacionado – seu site, a documentação do seu produto, suas conversas nos problemas do GitHub e Slack – a fim de fornecer um serviço que eu chamo montagem de contexto. Aprendi esse termo com Jack Ozzie, quando ele trabalhava com seu irmão Ray no Groove, um sucessor peer-to-peer do maior sucesso de Ray, Lotus Notes, que foi pioneiro no que ficou conhecido como gestão do conhecimento. Assim como o Notes, o Groove trouxe o trabalho de informações para espaços compartilhados onde você poderia pesquisar e-mails, calendários, documentos e dados de uma só vez.

Hoje em dia trabalhamos muito pesquisando no Slack, no Google Docs, no GitHub e em e-mails para construir contexto para o trabalho que realmente precisamos fazer. Se tivéssemos uma metapesquisa eficaz, isso ajudaria. Mas mesmo assim estaríamos apenas executando consultas de palavras-chave paralelas e fazendo o trabalho árduo de montagem de contexto em nossas cabeças ou transferindo o imposto para colegas de trabalho. O Unblocked visa aliviar a carga tributária cognitiva que as equipes de software suportam.

Esta foi minha chance de revisitar nosso doc sprint de 2022, munido do tipo de ferramenta que eu gostaria que tivéssemos naquela época. Um dos nossos objetivos era enriquecer os documentos com exemplos de expressões idiomáticas do SDK, juntamente com links para o código-fonte onde esses exemplos podem ser vistos no contexto. A capacidade do Unblock de encontrar tais exemplos foi provavelmente o maior benefício oferecido durante esta reescrita. A certa altura, eu estava procurando exemplos de código de plug-in que usasse uma mistura de uma função List (que preenche algumas das colunas de uma tabela Steampipe com os resultados de uma chamada de API primária) e uma função Hydrate (que preenche colunas adicionais com resultados de uma chamada de API auxiliar). As palavras “List” e “Hydrate” aparecem em todos os lugares: no código do próprio plugin SDK e no código de cada plugin. Se você está procurando um exemplo que combine os dois tipos de funções, uma pesquisa de código convencional é inútil. Mas você pode fazer uma pergunta ao Unblocked como esta:

E obtenha uma resposta como esta:

Este é um tipo de pesquisa profundamente diferente do que estamos acostumados. Não posso fingir que sei como funciona e não tenho certeza se alguém pode explicá-lo completamente, mas meu entendimento ingênuo é que quando você faz esse tipo de pergunta a um LLM você não está procurando palavras, você está procurando por um padrão. Ferramentas capazes de identificar e localizar tais padrões num corpus de documentos irão, penso eu, ajudar-nos a finalmente concretizar a promessa da gestão do conhecimento – no domínio do software, mas também de forma mais ampla.

No Data Exchange de Ben Lorica, Chris Wiggins fez uma pesquisa magistral sobre a história do que hoje chamamos de IA, que, ressaltou ele, costumava ser chamado de aprendizado de máquina, mas mesmo antes disso era conhecido como reconhecimento de padrões.

Veja como Ward Cunningham introduziu o pioneiro Portland Pattern Repository (que também era o wiki original do mundo).

Como outras ferramentas apoiadas por LLM, o Unblocked tem acesso a documentos globais, bem como aos documentos locais que pode ingerir. Isso me ajudou a descobrir as relações entre os esquemas que definem as tabelas Steampipe, as estruturas de dados correspondentes no AWS Go SDK que envolve as APIs subjacentes da AWS e as próprias APIs brutas. Nossos sistemas estão cada vez mais dispostos em camadas dessa maneira. A pesquisa orientada a padrões em código e documentação, tanto em contextos globais quanto locais, parece uma maneira poderosa de navegar pelas camadas.

Explicando os padrões

Meu objetivo era esclarecer os padrões suportados pelo SDK do plugin Steampipe e incorporados ao conjunto de plugins construídos sobre o SDK. Embora encontrar exemplos de tais padrões tenha sido a principal contribuição de Unblocked para a reescrita, também me ajudou a explicá-los. Não estávamos começando do zero — havia muito material tanto nos comentários do código-fonte quanto no site. Isso significava que eu poderia aplicar a regra 4 das Melhores Práticas para Trabalhar com Grandes Modelos de Linguagem: Peça explicações corais. Na formulação original da ideia de Mike Caulfield, sites de resposta a perguntas como Quora e StackOverflow convidam a coros de explicações.

Eu aplico a regra 4 de duas maneiras. Muitas vezes, hoje em dia, farei a mesma pergunta ao ChatGPT, Claude e Gemini. É rápido e fácil fazer isso e, para qualquer pergunta, a resposta de que os cliques pode vir de qualquer um dos três. Mas também pode ser valioso colocar a mesma questão várias vezes em um único LLM, formulada de maneiras diferentes para obter diferentes tipos e níveis de explicação. Neste caso, a documentação pré-existente provavelmente foi suficiente para um especialista como José Reyes, que pode saltar para uma base de código e intuir – imediata e profundamente – o que está acontecendo. Eu não sou assim e tenho certeza que muitos outros também não. Em uma aula de matemática, eu seria o tipo de aluno que não consegue entender uma explicação abreviada de uma prova, mas, em vez disso, precisaria ver as etapas da prova explicadas em detalhes, de preferência mostradas de algumas maneiras diferentes.

Pedir a um professor para fazer isso atrapalharia a aula, e é por isso que estou particularmente entusiasmado com o novo tutor de IA da Khan Academy, Khanmigo.

Da mesma forma, teria sido perturbador para mim pedir aos nossos arquitetos e desenvolvedores líderes essa reformulação. Na medida em que o Unblocked poderia entregá-los, eu fui desbloqueado – sem trocadilhos! – em meu esforço para compreender e explicar melhor nosso sistema. Não quero exagerar nesse efeito, que eu caracterizaria como limitado e incipiente, mas é real e aponta para uma nova maneira poderosa de obter compreensão do código.

Revendo as melhorias

À medida que trabalhava em cada seção da reescrita, solicitei repetidamente ao Unblocked minha proposta de nova versão e convidei a revisão. Às vezes, não encontrou nada para adicionar ou alterar. Esse foi um sinal de que a seção estava fazendo seu trabalho. Não é um sinal infalível, é claro! Mas mesmo assim é útil.

Às vezes, porém, o Unblocked fazia contribuições substanciais. Aqui está sua revisão de um rascunho completo.

Essas foram boas sugestões que incluí quase literalmente. Se fosse possível creditar Unblocked como coautor da solicitação pull que resultou deste exercício de reescrita, eu o faria. Parecia uma verdadeira colaboração, que é, na minha opinião, o melhor cenário para IA.

Testes de estresse para documentação

Não relacionado à reescrita aqui, recentemente tive uma pergunta sobre o Datatank, um recurso do Pipes (a versão hospedada do Steampipe) que persiste em resultados de consulta transitórios. Minha pergunta foi: você pode editar o SQL que define uma consulta personalizada do Datatank? Eu tinha quase certeza de que a resposta era sim, mas já fazia um tempo que não usava o recurso, então perguntei ao Desbloqueado e ele disse que não.

Verifiquei novamente e confirmei que você realmente pode editar esse SQL, então marquei a resposta de Unblocked como errada. Depois dei outra olhada na documentação e, com certeza, não dissemos explicitamente que você pode editar o SQL. Então retirei minha reclamação e adicionei esse esclarecimento ao documento.

Mais tarde fiz a mesma pergunta e obtive esta resposta.

Isso estava parcialmente correto. Sim, você pode editar o SQL. Mas não, você não precisa esperar até a próxima atualização agendada. Eu mesmo não tinha certeza disso, então fiz uma atualização de teste para confirmar que (como explica a nota que adicionei) a consulta é executada imediatamente e de acordo com a programação.

Então Desbloqueado não acertou totalmente. Mas, como sempre, você deve aplicar a regra 2: Nunca confie, sempre verifique. Desbloqueado fornece o link. Use-o!

Minha conclusão aqui foi algo que eu nunca havia considerado. Depois que ferramentas como o Unblocked ingerirem nossa documentação, podemos fazer perguntas que esperamos que os documentos respondam e verificar se realmente o fazem. Essas ferramentas podem até sugerir perguntas a serem feitas para realizar esses testes de estresse. E de fato, o Unblocked já faz isso.

Ajustar os documentos para levar em conta todas essas questões pode ser um exagero, mas é útil considerá-las.

Revisar e ampliar

Escrever documentação do zero é tão incomum quanto escrever código do zero. Mais normalmente, você atualiza, expande ou refatora documentos existentes. Minha expectativa era que uma ferramenta com LLM preparada com código e documentação pudesse fornecer uma ajuda poderosa, e o Unblocked o fez.

Não sei como medir o impulso que isso me deu. Mas sei que nunca mais vou querer empreender esse tipo de projeto sem uma ferramenta que me ajude a montar o contexto necessário.

A postagem Código em contexto: como a IA pode ajudar a melhorar nossa documentação apareceu pela primeira vez em The New Stack.