Pular para o conteúdo principal
Growth/
/
15 min

Docs-led growth: a documentação como canal de aquisição em web3

Em infraestrutura web3 o desenvolvedor decide dentro da documentação, não na landing page. A Kaleidos desmonta a arquitetura de doc que converte (quickstart curto, exemplo que roda, página de comparação, receita por caso de uso), o que medir no log da API em vez do analytics, e o que Alchemy, Stripe e Chainlink já fazem com llms.txt.

Resumo

Documentação é o canal de aquisição real de infraestrutura web3: 83,9% dos desenvolvedores usam doc técnica como recurso de aprendizado, acima do Stack Overflow. A doc que converte tem quatro peças (quickstart curto, exemplo que roda, página de comparação e receita por caso de uso) e se mede pelo tempo até a primeira chamada de API bem-sucedida, não por pageview.

Gabriel MadureiraGabriel Madureira

Docs-led growth: a documentação como canal de aquisição em web3

TL;DR

Continue por dentro

Um estudo denso por quinzena, direto no seu email.

Os bastidores de por que tokens e projetos crescem. Sem ruído, sem spam.

  • 83,9% dos desenvolvedores usam documentação técnica como recurso de aprendizado, à frente do Stack Overflow (80%), numa base de 48.822 respondentes (Stack Overflow Developer Survey 2024).
  • A a16z crypto descreve o go-to-market da Alchemy como product-led e channel-led, com "documentação para desenvolvedores, eventos e educação" listada como parte central do esforço (a16z crypto).
  • A Stripe tratou documentação como problema de engenharia de produto e abriu o Markdoc em maio de 2022 sob licença MIT, justamente para separar código de conteúdo (stripe.dev).
  • Doc virou superfície de citação por IA: a Stripe publica um llms.txt e uma versão .md de cada página, e a Chainlink publica um índice de navegação equivalente em docs.chain.link/llms.txt. O formato foi proposto por Jeremy Howard em setembro de 2024 (llmstxt.org).
  • A métrica de doc não é pageview. É tempo até a primeira chamada de API bem-sucedida e taxa de quickstart concluído, ambas medidas no backend, não no analytics da página.
  • O DORA mediu que qualidade de documentação multiplica o efeito de toda prática técnica estudada em 2022, em alguns casos por mais de 10 vezes (DORA).

O desenvolvedor decide na doc, não na landing page

Existe uma assimetria confortável no marketing de infraestrutura web3. Marketing controla a home, o blog e a campanha paga. Engenharia controla a documentação. E o comprador decide dentro do território que o marketing não controla.

O dado mais direto saiu do Stack Overflow Developer Survey de 2024: 83,9% dos desenvolvedores citam documentação técnica como recurso de aprendizado online, acima de Stack Overflow (80%) e de qualquer outro canal, numa base de 48.822 pessoas que responderam a essa pergunta específica (Stack Overflow). Não é preferência declarada de canal de mídia. É onde a pessoa está quando precisa resolver alguma coisa.

Em infraestrutura cripto isso é ainda mais agudo, por três razões que valem nomear.

A primeira é que o produto é invisível. Um RPC provider, um oráculo, uma SDK de carteira: nada disso tem screenshot que venda. A única demonstração honesta é a chamada funcionando.

A segunda é que o comprador é o usuário. Em infra web3 quem escolhe o provedor é a mesma pessoa que vai integrar e ser acordada às três da manhã quando o endpoint cair, e essa pessoa não é convencida por prova social genérica.

A terceira é que o custo de troca é baixo na entrada e altíssimo depois. Trocar de RPC provider na primeira semana é editar uma variável de ambiente. Trocar depois de seis meses em produção é um projeto. A janela de decisão é curta, acontece cedo, e acontece na doc.

Vale marcar a fronteira em relação a um argumento que já cobrimos antes: quando a infra tem token, o incentivo pode carregar parte da aquisição, e esse é um jogo diferente, com dinâmica própria de grants como mecanismo de go-to-market. Quando não tem token, sobra produto e sobra doc. É o quadrante que a Alchemy ocupa, e o motivo de o go-to-market dela funcionar sem token ser tão instrutivo.

O que a a16z já disse sobre isso, com todas as letras

O ensaio da a16z crypto sobre go-to-market em web3 é um dos poucos textos de fundo que trata documentação como linha de GTM. Ao descrever empresas de infraestrutura no modelo SaaS, o texto coloca "alcance focado em desenvolvedor e relações com desenvolvedores, incluindo documentação para desenvolvedores, eventos e educação" como muito importante (a16z crypto).

Sobre a MakerDAO, o mesmo texto observa que "melhor documentação para desenvolvedores e mais playbooks de integração" permitiram que outros projetos construíssem em cima em escala. A palavra que importa ali é escala: doc é o único ativo de GTM que atende mil integradores com o mesmo esforço marginal que atende um.

Isso não elimina o restante do funil B2B. Continua valendo o desenho que a Kaleidos usa em GTM B2B para infraestrutura web3, com as duas portas visíveis, autoatendimento e comercial. O ponto é que a porta de autoatendimento é literalmente a doc, e ela costuma ser a única que ninguém no time de marketing sabe dizer como está performando.

A arquitetura de doc que converte

Documentação que serve de canal de aquisição tem quatro peças com funções distintas. Confundir as quatro é o erro estrutural mais comum: um texto que tenta ser tutorial, referência e argumento comercial ao mesmo tempo não é nenhum dos três.

1. O quickstart de 5 minutos

O quickstart tem um objetivo só: produzir a primeira resposta bem-sucedida da API o mais rápido possível. Não é lugar de explicar arquitetura, listar parâmetros nem convencer ninguém.

O quickstart da Alchemy é um bom molde porque é curto e linear: criar uma chave de API, fazer a primeira requisição, integrar com viem, e só então partir para outras bibliotecas (Alchemy Docs). Quatro passos. A ordem é a coisa mais importante da página, e a ordem diz: chave primeiro, resposta segundo, entendimento depois.

Três regras que a Kaleidos aplica ao revisar quickstart de cliente:

  • Chave de API antes de qualquer conceito. Se o leitor precisa entender o que é um compute unit antes de conseguir uma chave, o quickstart está invertido.
  • Um caminho só. Quickstart com "escolha entre estas cinco linguagens e três frameworks" já é referência disfarçada. Escolha uma linguagem padrão, coloque as outras num seletor, e nunca peça decisão no primeiro minuto.
  • A resposta esperada, impressa na página. O leitor precisa comparar o que recebeu com o que devia receber. Sem o output esperado, o desenvolvedor não sabe se deu certo, e a etapa não conta como concluída.
A Chainlink resolve o problema do ambiente de outro jeito, e vale conhecer o truque: o caminho de entrada usa o Remix, IDE de contrato inteligente que roda no navegador, e cada exemplo de código tem link direto para abrir no Remix. O leitor sai do zero e chega a um contrato implantado sem instalar nada (Chainlink Docs). Instalação local é a maior fonte de abandono de quickstart em cripto, e o navegador é a forma mais barata de remover essa fricção.

2. O exemplo copiável

Exemplo de código em doc de infra tem uma exigência acima de todas: rodar. Não "ilustrar". Rodar, colado como está, na versão atual da biblioteca.

Isso soa óbvio e quase nunca é verdade. O padrão que falha é o exemplo escrito à mão no lançamento, com chave fictícia, endpoint que mudou de nome e versão de SDK de dois anos atrás. Ele passa no code review porque ninguém executa doc no CI.

Duas práticas resolvem quase tudo:

  • Exemplos extraídos de arquivos que rodam em teste. O trecho da página é gerado a partir de um arquivo real do repositório de exemplos, coberto por CI. Se o exemplo quebra, o build quebra, e alguém conserta antes de o leitor descobrir.
  • Chave de teste já preenchida. A Stripe é a referência aqui: a documentação injeta a chave de teste da conta logada dentro dos exemplos, e essa foi uma das razões declaradas para construir o Markdoc, que precisava suportar "injeção de chave de API, checklists e conteúdo condicional" sem misturar código e conteúdo (stripe.dev). O Markdoc foi aberto em maio de 2022 sob licença MIT.

3. A página de comparação

Esta é a peça que times de engenharia resistem a escrever e que times de marketing escrevem mal.

O desenvolvedor avaliando um provedor de infra vai comparar. A pergunta não é se ele vai buscar "alternativa a X" ou "X vs Y", é se ele vai encontrar a sua versão dessa comparação ou só a do concorrente. Deixar o espaço vazio não é neutralidade, é ceder a narrativa.

O que separa uma página de comparação útil de um panfleto:

  • Critérios que o leitor escolheria, não os que você ganha. Latência, cobertura de rede, limite de requisições, comportamento em reorg, política de rate limit, o que acontece no dia em que o serviço cai.
  • Casos em que o concorrente é a escolha certa. Uma comparação que perde em nenhuma linha não é lida como vitória, é lida como material de vendas. Admitir um caso de uso onde o outro é melhor é o que compra credibilidade para as outras linhas.
  • Números com data e método. Benchmark sem data é ficção. Benchmark sem método é ficção com gráfico.

4. As receitas por caso de uso

Quickstart resolve "como faço a primeira chamada" e referência resolve "quais são os parâmetros". Falta a camada do meio, onde mora a maior parte do valor comercial: "como eu faço a coisa que eu vim fazer".

Receita é uma página por intenção real. Não "guia de webhooks", e sim "notificar um usuário quando uma transferência de USDC cair na carteira dele". Não "referência de data feeds", e sim "liquidar uma posição usando preço de oráculo com verificação de staleness".

A regra de nomeação é simples: o título da receita é a frase que o desenvolvedor digitaria na busca. Título com o nome do produto em vez do nome do problema não é encontrado por quem ainda não conhece o produto, e receita existe justamente para essa pessoa.

Doc como superfície de SEO

Documentação tem uma vantagem estrutural sobre blog em busca: ela responde consultas de intenção terminal. Quem busca "chainlink price feed sepolia address" não está pesquisando, está executando. E a página que resolve essa busca ganha uma visita de alguém a um passo de integrar.

Três características tornam doc um ativo de busca melhor que a maioria dos blogs corporativos:

  • Cauda longa gigantesca. Cada método, cada código de erro, cada rede suportada é uma consulta possível. Uma mensagem de erro literal copiada do console é a consulta mais qualificada que existe na internet.
  • Renovação natural. Doc é atualizada porque o produto muda, não porque alguém agendou "revisar conteúdo antigo".
  • Ligação interna densa. Doc já é um grafo: referência aponta para guia, guia aponta para receita, receita aponta para referência.
O que costuma faltar é banal e custa caro: página de erro indexável. A maior parte dos sites de doc de cripto não tem uma página por código de erro, e quem colou o erro no Google acaba num fórum de terceiros ou numa issue do GitHub de 2023. Cada código de erro merece uma URL própria, com causa, correção e link para o guia certo.

A parte técnica dessa camada é a mesma que a Kaleidos cobre em SEO técnico para dApps e produtos web3: renderização, canonical entre versões e a decisão de qual versão da doc é indexada. Doc versionada sem canonical bem resolvido compete consigo mesma, e a versão de 2023 costuma ganhar da atual, porque acumulou links.

Doc como superfície de citação por IA

Aqui o terreno mudou rápido, e a maioria dos times de infra cripto ainda não reagiu.

Uma fatia crescente das primeiras integrações não começa com o desenvolvedor lendo a doc, e sim com um agente de código lendo a doc por ele. O que o assistente conhece, ou consegue buscar, define qual provedor entra no arquivo.

As empresas que levam isso a sério já publicaram infraestrutura para essa leitura:

  • Stripe. Publica um llms.txt que funciona como índice da documentação inteira, serve uma versão .md de cada página (docs.stripe.com/api.md, docs.stripe.com/testing.md) e expõe uma página de skills para agentes em docs.stripe.com/skills.md. O próprio índice instrui o agente a checar a versão atual do pacote no npm em vez de confiar em número memorizado (docs.stripe.com/llms.txt).
  • Chainlink. Publica um índice de navegação em docs.chain.link/llms.txt que se apresenta como guia para localizar a página mais relevante para uma tarefa, orienta a preferir páginas markdown e recuperar primeiro a menor página relevante, e adverte explicitamente contra confiar em endereços ou limites memorizados em vez de consultar a fonte.
O formato em si é recente: llms.txt foi proposto por Jeremy Howard em setembro de 2024, com uma versão 2 publicada em agosto de 2026, e a especificação exige apenas um H1 com o nome do projeto, um resumo opcional em blockquote e listas de links delimitadas por H2 (llmstxt.org).

O detalhe da Chainlink condensa a lição. O arquivo não tenta impressionar o modelo, tenta impedir que ele invente um endereço de contrato. Em cripto, endereço errado não é erro de conteúdo, é perda de fundos.

O trabalho concreto cabe em uma sprint:

  1. Publicar llms.txt na raiz da doc, com H1, resumo e listas por produto.
  2. Servir uma versão markdown de cada página, com URL previsível.
  3. Colocar informação volátil (endereços, limites, versões) em páginas próprias e curtas, e apontar para elas em vez de repetir o valor em dez lugares.
  4. Escrever cada página assumindo leitura isolada. Contexto implícito na navegação some quando a página é consumida sozinha.

Como medir: as duas métricas que valem

Doc é medida errado em quase todo lugar porque a métrica fácil está no lugar errado. Pageview de documentação sobe quando o produto está confuso. Tempo na página sobe quando a pessoa está perdida. As duas métricas mais reportadas são ambíguas por natureza.

As métricas que a Kaleidos usa para doc de cliente de infra vivem no backend, não no analytics da página:


MétricaDefiniçãoOnde medeO que faz subir
Tempo até a primeira chamada bem-sucedidaMinutos entre criação da chave de API e primeira resposta 200 daquela chaveLog da APIQuickstart curto, chave sem fricção, exemplo que roda
Taxa de quickstart concluído% das chaves criadas que chegam à última etapa do quickstart em 7 diasLog da API mais evento de páginaOrdem correta dos passos, output esperado visível
Taxa de erro na primeira semana% de chamadas com erro 4xx por chave novaLog da APIPágina por código de erro, exemplo atualizado
Chaves que viram tráfego pago% das chaves gratuitas que passam do limite grátis em 90 diasBillingReceitas por caso de uso, não o quickstart
Citação por assistenteSe o agente cita a doc oficial ao ser perguntado sobre a tarefaTeste manual recorrentellms.txt, páginas markdown, fonte canônica
O tempo até a primeira chamada bem-sucedida é a única métrica de doc que o time comercial entende sem tradução: é o equivalente, em infra, do tempo até o primeiro valor em SaaS. E nenhuma dessas métricas é obtida com o time de conteúdo trabalhando sozinho. Todas exigem instrumentação no produto. Essa é a razão real pela qual doc quase nunca é medida como canal: a medição atravessa duas áreas, e projeto que atravessa duas áreas costuma virar tarefa de ninguém.

O plano gratuito é a instrumentação mais barata dessa medição. A Alchemy oferece, em 26 de agosto de 2026, 30 milhões de compute units por mês, 15 requisições por segundo e 5 apps no plano gratuito (Alchemy Pricing). Cada chave gratuita criada é um evento datado de intenção, e cada primeira chamada com aquela chave é uma conversão observável. Sem tier gratuito com chave imediata, a doc perde o instrumento de medida junto com o funil.

Quem escreve

O desenho de responsabilidade importa mais que o talento individual. O modelo que funciona nas contas de infra tem três papéis:

  • Engenharia é dona da correção. Todo exemplo, toda assinatura de método, todo limite. Nada sai sem revisão de quem mantém o código. É a única parte não delegável.
  • Conteúdo é dono da ordem e da linguagem. Qual é o primeiro passo, o que sai da página, qual palavra o leitor usaria. Engenheiro escreve na ordem em que o sistema foi construído, e o leitor precisa da ordem em que o problema aparece.
  • Suporte é dono da pauta. A fila de tickets é o backlog de doc mais confiável que existe. Toda pergunta respondida duas vezes no Discord é uma página que falta.
O que a Kaleidos vê quebrar com mais frequência não é o texto, é o gatilho: não existe um momento definido em que a doc é atualizada, e sem regra ela perde para qualquer coisa com prazo. A regra que funciona é ligar a doc ao release: mudança que altera comportamento público não está pronta enquanto a página não foi atualizada e o exemplo não passou no CI.

Vale registrar o que o DORA mediu sobre isso, mesmo tratando de documentação interna. No State of DevOps de 2022, qualidade de documentação amplificou o efeito de todas as práticas técnicas estudadas, com saltos como o da integração contínua (de 34% para 750%) e o do desenvolvimento trunk-based (de 36% para 1525%) ao comparar times com documentação abaixo e acima da média (DORA). A leitura para fora é a mesma: doc não é uma alavanca entre outras, é o multiplicador das outras.

Os quatro erros clássicos

1. Doc gerada automaticamente sem narrativa. Gerar referência a partir de OpenAPI ou de comentário no código é correto e necessário. O erro é achar que isso é a documentação. Referência gerada responde "quais parâmetros esse método aceita" e nunca responde "por que eu usaria esse método". Sem a camada narrativa por cima, o site de doc é um dicionário: perfeito para quem já sabe a palavra, inútil para quem está aprendendo a língua.

2. Versão desatualizada indexada. É o erro mais caro porque é silencioso. A doc atual está certa, mas o Google entrega a de 2023, e o desenvolvedor integra contra uma API que não existe mais. Sintoma típico: pico de tickets sobre um método removido meses atrás. Correção: canonical apontando para a versão estável, banner de versão antiga com link para a atual, e nunca deixar a versão antiga sem aviso.

3. Exemplo que não roda. O custo merece ser dito na moeda certa: um exemplo quebrado no quickstart não gera ticket, gera abandono. A pessoa não escreve para reclamar, testa o concorrente. O dano não aparece em painel nenhum, e é isso que o torna tolerável por tempo demais.

4. Doc escrita para quem já decidiu. O sintoma é a página que começa com "instale nosso SDK": ela assume que a escolha já foi feita. Toda doc de infra tem duas audiências simultâneas, o integrador e o avaliador, e a maioria escreve só para o primeiro.

O que fazer na segunda de manhã

Um roteiro de duas semanas que cabe em qualquer time de infra, sem contratar ninguém:

  1. Cronometre. Pegue uma pessoa do time que não conhece o produto e peça para chegar à primeira chamada bem-sucedida usando só a doc pública. Cronometre e anote onde ela travou. Esse número é a linha de base, e costuma ser constrangedor.
  2. Instrumente. Meça no log da API o tempo entre criação da chave e primeira resposta 200. É uma consulta, não um projeto.
  3. Corte o quickstart pela metade. Tudo que não for necessário para a primeira resposta sai da página e vira link.
  4. Rode os exemplos no CI. Comece pelos cinco exemplos das páginas mais visitadas.
  5. Publique llms.txt e as versões markdown. Comece pelo índice e pelas páginas de referência.
  6. Escreva três receitas nomeadas pelas três perguntas mais repetidas no suporte nos últimos 90 dias.
  7. Publique uma página de comparação com pelo menos um caso admitido em que o concorrente é a escolha certa.
A pergunta que o time deve conseguir responder ao fim disso é uma só, e é a mesma que a Kaleidos faz na primeira semana de toda conta de infraestrutura: quanto tempo, em minutos, separa um desenvolvedor que nunca ouviu falar do produto da primeira chamada de API que funciona. Enquanto ninguém souber esse número, a documentação não é um canal, é uma esperança.

Perguntas frequentes

O que é docs-led growth?

É tratar a documentação técnica como canal de aquisição, com dono, meta e medição, e não como obrigação de engenharia. A lógica é que o comprador de infraestrutura decide dentro da doc: 83,9% dos desenvolvedores citam documentação técnica como recurso de aprendizado, à frente do Stack Overflow, com 80% ([Stack Overflow Developer Survey 2024](https://survey.stackoverflow.co/2024/developer-profile/)).

Como medir se a documentação está trazendo clientes?

Pelo tempo entre a criação de uma chave de API e a primeira resposta 200 daquela chave, e pela taxa de quickstart concluído em sete dias. As duas métricas vivem no log da API, não no analytics da página. Pageview e tempo na página são ambíguos: sobem quando o produto está confuso.

O que é llms.txt e por que uma infra cripto deveria publicar?

É um arquivo markdown padronizado que indexa a documentação para agentes de IA, proposto por Jeremy Howard em setembro de 2024 ([llmstxt.org](https://llmstxt.org/)). Stripe e Chainlink já publicam o seu. O da Chainlink orienta o agente a buscar a página canônica em vez de confiar em endereços memorizados ([docs.chain.link/llms.txt](https://docs.chain.link/llms.txt)), o que em cripto é redução de risco além de aquisição.

Quem deveria escrever a documentação: engenharia ou marketing?

Os dois, com responsabilidades separadas. Engenharia é dona da correção (exemplos, assinaturas, limites) e nada sai sem revisão de quem mantém o código. Conteúdo é dono da ordem dos passos e da linguagem. Suporte é dono da pauta: toda pergunta respondida duas vezes no Discord é uma página que falta.

Gostou deste estudo?

A Kaleidos faz isso pelo seu projeto cripto.

Somos a agência cripto-nativa do Brasil. Estratégia, conteúdo e growth do jeito de quem entende o mercado on-chain. Fale com a gente e vamos construir atenção juntos.

Gostou? Compartilhe com quem precisa ler.

Gabriel Madureira

Gabriel Madureira

Kaleidos

A Kaleidos disseca o que faz tokens e projetos crescerem, e aplica isso em quem constrói no cripto/web3.

Agendar diagnóstico de 30 min

Receba os próximos estudos

Um estudo denso por quinzena, direto no seu email.

Descubra mais artigos

Trabalhe com a Kaleidos

Quer esse nível de estratégia no seu projeto cripto?

Somos a agência cripto-nativa do Brasil. Peça uma proposta grátis e veja como podemos construir atenção, autoridade e growth pro seu projeto.