Human Insight + LLM Grunt Work = Solução Criativa de Publicação

Se você publicar a documentação do produto em um site, esse poderá ser um padrão familiar. Você escreve um rascunho inicial no Google Docs para que sua equipe possa revisar e propor alterações. É um ambiente de autoria rico no qual você pode inserir imagens colando bits copiados de telas e criar e reorganizar tabelas facilmente. Quando a equipe chega a um consenso, você tem uma bela representação da página da web que gostaria que aparecesse em seu site.

Mas como você faz isso acontecer? Nesta postagem, veremos um método surpreendentemente simples e comprovadamente eficaz. No nosso caso, está ajustado para um fluxo de trabalho que empurra Repositórios GitHub em sites baseados em Next.js hospedados por Vercel, então nosso texto Markdown e imagens associadas são copiados para esses repositórios. Mas o método funcionará para qualquer sistema de publicação orientado a Markdown.

Por que não usar a sintaxe do Markdown no Google Docs e passá-la para o Markdown publicável?

A solução ingênua é, obviamente, apenas exportar o Google Doc como HTML. Isso leva você até lá, mas o último quilômetro é uma ladeira escorregadia. O Google Docs não permite criar estilos personalizados para alinhar elementos com seus equivalentes em sua página da web publicada. E as imagens são provenientes de googleusercontent o que é conveniente – elas parecem funcionar magicamente – mas você provavelmente deseja que essas imagens sejam armazenadas como arquivos nomeados em seu sistema de publicação.

Então, o que tenho visto acontecer, em vários ambientes diferentes, é a transferência manual e a reformatação que se tornam um imposto sobre o benefício colaborativo do Google Docs.

Eu havia tentado resolver esse problema algumas vezes na era pré-LLM, então, para começar, revisei o que minha nova equipe de assistentes poderia trazer para a festa. Alimentar uma exportação HTML do Google Docs para o Markdownify do Python nos deixou tentadoramente perto, mas essa última milha é realmente um deslizamento escorregadio nas ervas daninhas da conversão de documentos.

Então me ocorreu: as pessoas já estão escrevendo crases triplos para blocos de código, crases únicos para código embutido, ** e * para negrito e itálico e links e listas no estilo Markdown. Por que não usar essa sintaxe do Markdown no Google Docs e passá-la para o Markdown publicável? Acabou sendo uma ideia realmente frutífera e fácil de implementar.

Simplificação de padrão progressivo

Aqui está a sintaxe que estou usando para identificar imagens no Google Docs.

(imagem: imagem_1 70%)

Veja como fica no HTML exportado.

(imagem: image_1 70%)

Aqui está a versão Markdownified dele.

(imagem: my_image_1 70%) n n!()(https://lh7-us.googleusercontent.com/FcQFpX3FcEHFx0WmbZlMSKryKxd9hnkdtvSwnlS-v5Y92x6VKfYFhb_b8yJtkv6q8j2gARKB5AGfQRJlMVpz4JbTzdQEg0GiH nreS7U0bD-Xeho ZT6S_DydXtSgpnlPutG8pso1XBZChKvl0)

Agora duas coisas precisam acontecer: a imagem precisa ser baixada para um arquivo com o nome indicado, e toda a string precisa ser substituída por este elemento.

Já que o site é alimentado por Markdown, por que não um link no estilo Markdown? Você não pode especificar o atributo opcional de largura no Markdown, portanto a sintaxe HTML é necessária. (Por que os colchetes duplos? Há outro nível aqui: para atributos, o sistema de publicação requer sintaxe JSX.)

Aqui estão as funções que fazem o trabalho.

Veja o código no Gist.

Meus assistentes ajudaram com a codificação, como sempre, mas não tiveram a ideia, nem eu esperava que o fizessem. Embora os grandes modelos de linguagem (LLMs) possam certamente ser patos de borracha úteis, penso que, por enquanto, este tipo de solução criativa e não óbvia exigirá uma visão humana. Talvez a inspiração da cadeia de pensamentos pudesse ter me levado até lá e, se assim fosse, ficaria encantado em saber como.

Mas enquanto isso, estou muito grato pela ajuda na codificação. Nesse caso, isso incluiu escrever a expressão regular, testá-la e depois revisá-la para usar o formato longo com comentários. Sou melhor ter uma ideia como essa do que acertar os detalhes, por isso agradeço a ajuda.

Por favor, ChatGPT, não escreva código a menos que eu peça!

Bate-papoGPT realmente quer codificar, e estou descobrindo que ainda é difícil mantê-lo focado na estratégia.

Essa é uma frase que nunca imaginei que escreveria. Mas, à medida que eu trabalhava neste exercício, fiquei cada vez mais frustrado com a ânsia do ChatGPT e do Claude de mergulhar direto na codificação. Pedi a ambos que se abstivessem para que pudéssemos primeiro discutir a estratégia. Claude respondeu muito bem a esse pedido, mas ChatGPT estava teimosamente determinado a escrever código.

Quando mencionei isso no Mastodon, Josh Kellendonk respondeu prestativamente.

“Adicionei instruções ao prompt da minha base de usuários para não gerar código, a menos que solicitado explicitamente. O ChatGPT tem se comportado muito melhor desde então.”

Foi novidade para mim que você pode fazer isso por meio do link “Personalizar ChatGPT” no menu suspenso do seu perfil. E isso parece ter ajudado. Mas uau, ChatGPT realmente quer codificar, e estou descobrindo que ainda é difícil mantê-lo focado na estratégia.

Capturas de tela sem atrito

As capturas de tela são fundamentais para a documentação do software. Como desenvolvedores, usamos palavras e imagens de telas para explicar os vários estados em que os aplicativos podem estar. Se a criação e a manutenção das imagens forem caras, usaremos menos delas do que idealmente. É fácil capturar uma região de uma tela e talvez ajustá-la em um editor de imagens.

Mas há um custo nada trivial para mover essa imagem para o sistema de publicação. Você deve nomeá-lo no editor de imagens, salvá-lo no lugar certo e depois inserir uma referência a ele na página onde será exibido. E quando a UX do aplicativo muda, você precisa refazer essas etapas.

Reduzir essa sobrecarga tem sido um grande benefício dessa abordagem. Basta capturar bits de uma tela, colá-los em um Documento Google, escrever um nome descritivo (que também serve como texto alternativo) e pronto. Você termina em segundos e, se precisar revisar, é igualmente rápido.

Também posso imaginar um benefício indireto. Em “Como aprender ferramentas de software desconhecidas com ChatGPT”, vimos como agora é útil fazer upload de imagens de estados de aplicativos. À medida que a distinção entre texto e imagens de texto desaparece, as imagens tornam-se sugestões ricas que podem aumentar (ou mesmo substituir) as descrições verbais.

Experimentei esse modo poderoso pela primeira vez quando aprendi como traçar uma equação em uma ferramenta desconhecida, o GeoGebra, mostrando capturas de tela do ChatGPT de esforços fracassados. Acho que isso foi eficaz porque o GeoGebra é uma ferramenta popular que está bem representada no corpus de documentos dos quais os LLMs se alimentam.

Quanto mais estados do aplicativo representados pictoricamente nos documentos, mais provável será que a captura de tela capturada pelo usuário seja um prompt eficaz.

Conforme observado em “Como a IA pode ajudar a melhorar nossa documentação”, estamos fazendo uso eficaz do Unblocked, que ingeriu nossa documentação e pode responder perguntas com a ajuda desse corpus. Ele ainda não funciona com imagens, mas, se ganhar essa capacidade — e/ou à medida que os documentos chegarem aos LLMs públicos — as capturas de tela se tornarão uma forma alternativa poderosa de fazer perguntas como: Como cheguei a esta tela? O que deu errado? Para onde devo ir a seguir? Quanto mais estados do aplicativo representados pictoricamente nos documentos, mais provável será que a captura de tela capturada pelo usuário seja um prompt eficaz.

Se as coisas acontecerem assim, será muito diferente do que eu imaginava. Sempre me incomodou termos que escrever documentos que dizem coisas como: “Clique no botão Salvar (no canto superior direito da tela)”. Minha ideia sempre foi que a plataforma web oferece uma solução melhor: links. Se a área de superfície da URL de um aplicativo fosse suficientemente rica, você poderia simplesmente citar o link resultante de seguir essa instrução.

Mas há um limite prático para a quantidade de estado do aplicativo que você pode representar em uma URL. E, em última análise, o estado que importa é aquele que é renderizado na tela. Portanto, acho que as capturas de tela desempenharão um papel ainda mais importante do que já desempenham. E menos atrito editorial significa que podemos ter mais deles.

Revisão e revisão integradas

Embora a publicação simplificada de capturas de tela seja boa, a maior vantagem vem da revisão e revisão no Google Docs; que, para o bem e para o mal, tornou-se o padrão de colaboração de fato para muitos de nós. Embora Vercel suporte comentários em rascunhos, você não pode simplesmente clicar em “Aceitar” para incorporar uma sugestão em um documento publicado. E é difícil acompanhar os comentários em dois lugares.

Aceitar sugestões no Google e, assim, atualizar automaticamente a página publicada é muito mais limpo e simples. As alterações solicitadas também podem ser muito mais fáceis de fazer. Prefiro adicionar uma coluna a uma tabela em um Documento Google do que discutir o Markdown em um editor de texto!

Claro, o Google Docs tem sua cota de bugs. Um que me incomodou neste projeto: atribuir títulos de nível H próximos ao texto normal. Pode ser complicado separar os dois e, embora seja bom ver títulos estilizados em um documento do Google, posso voltar a usar títulos Markdown. Mas isso é um detalhe menor, porque no geral esse método híbrido tem sido uma grande vitória.

A postagem Human Insight + LLM Grunt Work = Creative Publishing Solution apareceu pela primeira vez em The New Stack.