Como liderei a reescrita de 2.030 páginas da documentação da Azion
Numa quinta-feira, viramos o domínio da documentação da Azion. Começou a chegar tráfego nas páginas que os agentes tinham escrito e que o nosso time vinha revisando havia semanas. Eram 2.030 páginas em dois idiomas, incluindo 372 guias e 27 casos de uso.
Eu liderei o projeto e o time. Também ajudei a desenvolver as skills, o guia de estilo e a base de conhecimento que os agentes consultavam. O projeto levou mais ou menos três meses. Eu diria que um terço desse tempo foi de preparação, entre escrever as instruções, testar o que saía delas e montar os benchmarks.
Uma pergunta acompanhou esse trabalho. Se você pede a um agente que instale uma ferramenta, quem vai ler o guia de instalação? Provavelmente o agente. E se o comando do guia estiver errado, dá pra escrever uma explicação ótima de como executar um comando que continua errado. Foi um problema bem concreto pra gente, porque parte da documentação antiga já estava desatualizada.
Por onde começamos
Dividimos a reescrita por produto. Para cada um, reunimos a referência técnica, os guias e os tutoriais. A ideia era que você conseguisse tanto consultar um detalhe do produto quanto entender o suficiente para usá-lo no seu cenário. Para organizar esse material, usamos o Diátaxis.
| Se você quer… | O que procurar |
|---|---|
| Aprender fazendo, com alguém guiando os passos | Tutorial |
| Resolver um problema que você já tem | Guia prático (how-to) |
| Conferir uma informação técnica específica | Referência |
| Entender como algo funciona e por quê | Explicação |
Na documentação de produto, gastamos mais tempo com referência. Depois, quando chegamos às ferramentas de desenvolvimento, a prioridade mudou. Quem vai usar uma CLI costuma ter duas dúvidas logo de cara. Como eu instalo? E como eu uso? Ainda precisávamos da referência, mas fazia sentido dedicar mais espaço aos primeiros comandos.
O que o agente tinha à mão
A documentação antiga era o ponto de partida. Para orientar a escrita, produzimos um guia de estilo. Para conferir o que as páginas diziam sobre os produtos, demos aos agentes acesso a outro repositório, o knowledge-base. Ali eles podiam consultar as especificações de engenharia e o material de go-to-market (GTM), que explicava como a Azion apresentava seus produtos e quais termos usava.
Organizamos essa base com o Open Knowledge Format (OKF), apresentado pelo Google Cloud em 12 de junho de 2026. São arquivos Markdown em diretórios, com metadados em YAML para identificar o tipo, o título e o recurso de cada entrada. Os links conectam conceitos relacionados. A gente podia ler esses arquivos diretamente, e os agentes consultavam o mesmo conteúdo por um servidor MCP que rodava na máquina. O Google Cloud explica o formato aqui.
No Claude Code, usamos o Fable 5.1 para planejar cada etapa. Ele também ficava disponível como advisor em todos os prompts. Quem executava o trabalho era o Opus 5.5. Era ele que usava as skills, consultava a base e decidia quando pedir orientação ao Fable.
Quando o Opus fazia essa consulta, o Fable recebia a conversa até ali, inclusive as instruções e os resultados das ferramentas. Com isso, podia sugerir um plano ou uma correção de rumo. O Opus então seguia com a tarefa. Quem quiser ver como essa troca funciona pode consultar a documentação da advisor tool.
Como a gente conferia um comando
Voltando ao exemplo da instalação, a skill instalava a CLI e tentava executar os comandos que encontrava na página antiga. A verificação dependia do que ela estava reescrevendo. Para uma chamada de API, consultava a documentação pública da API. Para uma tarefa no console, navegava pela interface e conferia o comportamento do produto.
Quando a skill não conseguia confirmar alguma coisa, registrava a dúvida num arquivo chamado open-questions.md. Aí entrava o time de DevRel. Às vezes bastava revisar o trecho. Em outros casos, precisávamos conversar com quem desenvolvia o produto para entender como ele funcionava e o que deveríamos escrever.
A regra para a escrita dependia da origem da informação. Se faltava evidência para acrescentar uma afirmação nova, a skill deixava o trecho de fora. Se a afirmação já estava na documentação, ela podia continuar na página enquanto a gente investigava. As pendências ficavam no acompanhamento interno de DevRel. Muitas se resolviam em poucas horas.
Escrita, revisão, benchmark e propostas de melhoria
Conforme os agentes terminavam as páginas, abriam pull requests (PRs). O time ia revisando o que chegava. Em paralelo, rodávamos uma skill de benchmark para comparar nossas páginas com a documentação dos três maiores concorrentes que consideramos no projeto.
A cada rodada, a skill gerava de 10 a 20 perguntas que um desenvolvedor ou um agente poderia fazer sobre aquele assunto. A gente queria saber onde era mais fácil encontrar a informação, qual página ajudava a entender melhor o assunto e até que ponto a resposta resolvia a dúvida. Era assim que tentávamos escrever uma documentação mais útil do que as alternativas, inclusive para quem delegava a leitura a um agente.
Os relatórios de revisão e de benchmark também serviam para ajustar a própria escrita. No fim de cada execução, uma subskill de self-improvement lia os relatórios e propunha mudanças. Toda sugestão passava por uma pessoa antes de entrar na skill de escrita ou no guia de estilo.
Uma delas foi encurtar frases e parágrafos para facilitar a vida de quem estava lendo. No guia público, o limite é de 20 palavras por frase em tutoriais e how-tos, e 25 em referências e explicações. Cada parágrafo trata de um assunto e pode ter até seis frases. Essa conta vale para a prosa. Um comando comprido, sua saída ou uma célula de tabela ficam de fora. Veja os exemplos no guia de estilo.
Usamos Mermaid nos diagramas da documentação por um motivo. Cada diagrama nasce de uma definição em texto, que descreve as etapas e as conexões entre elas. O build do site lê essa definição e desenha o diagrama que você vê. Quando um agente consulta a documentação em Markdown, ele recebe a definição junto com a explicação do fluxo. Essa escolha está no guia para pessoas e agentes.
O que medimos
Além do nosso benchmark, usamos o Lightsage e o Orank para comparar a documentação com a dos concorrentes. No Lightsage, acompanhamos a pontuação geral de relevância. No Orank, a pontuação do domínio passou de 47 para 87 durante o projeto. Dos critérios que acompanhamos, tivemos 20/20 em Discovery, 28/30 em Access e 30/40 em Usability. Outros critérios também entram na nota geral.
Nossa leitura foi que, se um agente encontra e entende a resposta com mais facilidade, ele pode chegar mais rápido a uma solução da Azion quando compara as alternativas. As avaliações externas reforçaram essa hipótese. Saber se o desenvolvedor continuou usando o produto depois é outra medição que eu gostaria de fazer.
A última semana, já com as páginas escritas
Reservamos a última semana para colocar a documentação no ar na própria Azion. O site usa Astro para gerar páginas estáticas. Configuramos cache nos datacenters da Azion e um cache de duração menor no cliente. Como tanto as páginas quanto os diagramas eram texto, usamos a compressão GZIP da Azion para reduzir o volume transferido. Também ajustamos o WAF, o firewall da aplicação. O build com Astro está descrito no nosso fluxo de docs as code.
Acompanhamos o TTFB, quanto tempo leva para chegar o primeiro byte da resposta, e o FCP, quanto tempo leva para aparecer o primeiro conteúdo na tela. O que eu percebia navegando era que, depois de abrir algumas páginas, as próximas apareciam quase na hora. Foi com essa configuração que viramos o domínio naquela quinta-feira.
Onde entra GTM
Se você está avaliando uma plataforma, um dos 27 casos de uso pode mostrar como ela resolve um problema parecido com o seu. Daí você escolhe um dos 372 guias para experimentar. Agora pensa no que acontece se você passar essa tarefa para um agente. A decisão de adotar o produto continua sendo sua, mas parte da experiência de usar o produto pela primeira vez acontece na conversa com ele.
É por isso que eu considero os agentes parte do público de DevRel. Eles leem a documentação e trabalham a serviço de quem desenvolve. Para entender o efeito disso na adoção, eu acompanharia o que acontece depois que o agente termina a tarefa. O desenvolvedor consegue voltar à plataforma e seguir por conta própria?
Se quiser experimentar esse caminho, na página inicial da documentação tem um prompt que você pode levar para o seu agente e as instruções para conectar a documentação via MCP. Abrir a documentação em português · Acessar docs.azion.com.