---
title: "Como liderei a reescrita de 2.030 páginas da documentação da Azion"
description: "Como o time de DevRel da Azion combinou agentes de IA, revisão humana e benchmarks para reescrever 2.030 páginas de documentação em dois idiomas."
author: Bruno Germano
lang: pt-BR
canonical: https://egermano.com/artigos/2026-11-11-reescrita-documentacao-azion
date: "2026-11-11 10:00:00 -0300"
updated: "2026-11-11 10:00:00 -0300"
---

# 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](https://diataxis.fr/start-here/).

| 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](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing).

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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/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](https://www.azion.com/en/documentation/style-guide/writing/sentence-structure/).

```mermaid
---
config:
  swimlane:
    ignoreCrossLaneEdges: false
    optimizeRanksByCrossings: false
---
swimlane-beta TB
    %% Raias sem bordas mantêm o fluxo principal no eixo de Documentação produzida.
    %% Os prefixos dos IDs estabilizam a ordem de leitura ao resolver os ciclos.
    subgraph esquerda[" "]
        b_legada["Documentação legada"]
        a_estilo["Guia de estilo"]
        g_pr["Pull Requests criadas pelos agentes"]
        h_revisao_humana["Revisão humana das Pull Requests"]
    end

    subgraph centro[" "]
        e_escrita["Escrita da documentação"]
        f_documentacao["Documentação produzida"]
        i_revisao["Revisão"]
        j_relatorio_revisao["Relatórios de revisão"]
        m_melhoria["Subskill de self-improvement"]
        n_propostas["Propostas para a skill de escrita e o guia de estilo"]
        o_avaliacao["Avaliação humana"]
        p_mudancas["Mudanças aprovadas"]
    end

    subgraph direita[" "]
        c_base["knowledge-base: GTM e Engineering em OKF"]
        d_mcp["MCP local na máquina"]
        k_benchmark["Benchmark comparativo com três concorrentes"]
        l_relatorio_benchmark["Relatórios de benchmark"]
    end

    style esquerda fill:none,stroke:none
    style centro fill:none,stroke:none
    style direita fill:none,stroke:none

    b_legada --> e_escrita
    a_estilo --> e_escrita
    c_base --> d_mcp
    d_mcp --> e_escrita
    e_escrita --> f_documentacao
    f_documentacao --> g_pr
    g_pr --> h_revisao_humana
    f_documentacao --> i_revisao
    i_revisao --> j_relatorio_revisao
    f_documentacao --> k_benchmark
    k_benchmark --> l_relatorio_benchmark
    j_relatorio_revisao --> m_melhoria
    l_relatorio_benchmark --> m_melhoria
    m_melhoria --> n_propostas
    n_propostas --> o_avaliacao
    o_avaliacao -->|"Sugestão aprovada"| p_mudancas
    p_mudancas --> e_escrita
    p_mudancas --> a_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](https://www.azion.com/en/documentation/style-guide/how-we-docs/for-people-and-agents/).

## 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](https://www.azion.com/en/documentation/style-guide/how-we-docs/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](https://www.azion.com/pt-br/documentacao/) · [Acessar docs.azion.com](https://docs.azion.com).