O projeto de código aberto Docsy, criado pelo Google para construir sites de documentação usando o gerador de sites estáticos Hugo, passa para a Linux Foundation em um momento em que a documentação técnica se tornou uma fonte direta para agentes de inteligência artificial, e não apenas para desenvolvedores.
Erin McKean, engenheira de relações com desenvolvedores do Google e membro do comitê diretor do Docsy, anunciou a medida durante uma palestra realizada na quarta-feira na cúpula de código aberto da Linux Foundation na Europa, em Praga. A transferência baseia-se parcialmente na disseminação do Docsy dentro do ecossistema de projetos relacionados à fundação; até o final de 2024, cerca de 2.200 projetos o utilizavam, entre eles projetos da Cloud Native Computing Foundation, como Kubernetes, OpenTelemetry, gRPC e Jaeger.
Um projeto de documentação voltado para um público automatizado
O Docsy foi anunciado pela primeira vez em 2019. Trata-se de um tema de código aberto dedicado à documentação técnica, que pode ser usado com projetos abertos ou privados. No entanto, as mudanças recentes concentram-se na forma como as ferramentas de inteligência artificial acessam o conteúdo e no formato das instruções de que essas ferramentas precisam para executar tarefas relacionadas aos projetos.
Desde a versão 0.15.0, lançada em maio, o Docsy consegue gerar uma versão Markdown de cada página, além da versão HTML habitual, e também pode gerar um arquivo llms.txt que fornece um índice do conteúdo do site. Ambos os recursos são opcionais e experimentais.
Na versão 0.16.0, lançada em julho, foi adicionado um guia de atualização elaborado para que um assistente automatizado possa segui-lo, incluindo pré-requisitos, etapas e processos de verificação. Já a versão 0.17.0, lançada em agosto, acrescentou uma instrução oculta no topo de cada página para usuários que ativam o llms.txt, direcionando os agentes visitantes ao índice do site. Esse recurso também continua experimental.
O que muda na prática?
O Docsy transforma parte da tarefa de aprimorar a documentação: ela deixa de consistir apenas em formatar páginas para leitura humana e passa a organizar o conteúdo de modo que modelos e agentes possam encontrá-lo, compreendê-lo e segui-lo. Para projetos que dependem de colaboradores ou usuários externos, isso pode significar direcionar as ferramentas de inteligência artificial para uma versão mais clara das instruções, em vez de deixá-las inferi-las a partir de páginas HTML públicas.
McKean afirma que uma documentação melhor pode reduzir as perguntas rotineiras que chegam aos mantenedores, pois as respostas ficam disponíveis aos usuários antes da intervenção de um maintainer. Esse é um possível benefício operacional para os projetos, mas não significa, por si só, que os agentes compreenderão o conteúdo corretamente ou que a documentação se tornará automaticamente precisa.
O próximo passo: medir a legibilidade para agentes
A equipe do Docsy trabalha no que chama de AF documentation scores, ou seja, pontuações sobre a adequação da documentação para agentes. O objetivo é oferecer aos mantenedores uma métrica para avaliar a capacidade das ferramentas de inteligência artificial de descobrir, navegar e consumir a documentação, em vez de depender apenas de suposições.
A fonte ainda não esclarece qual será o formato dessa métrica, seus critérios finais ou a data de lançamento. Além disso, os recursos Markdown e llms.txt, bem como as instruções associadas a eles, são opcionais e experimentais; portanto, seu impacto prático continua dependendo da adoção pelos projetos e da qualidade do conteúdo original que eles produzem.