Por que deixamos de usar o Notion para a documentação do produto

Eu costumava colocar tudo no Notion. Manual interno, especificações do produto, FAQ voltado para clientes, exemplos de API, o runbook para a escala de plantão, o changelog, o guia de integração pela metade que ninguém lia. Um espaço de trabalho, uma caixa de pesquisa, um conjunto de permissões. Foi ótimo por cerca de dezoito meses.

Então tentamos aumentar o tráfego da documentação. Depois tentamos adicionar um segundo idioma. E então um cliente perguntou por que a página que estava lendo estava três versões atrás da API. Quando migrei tudo do Notion, tinha uma lista de erros que gostaria que alguém tivesse me entregado no primeiro dia.

Esta é essa lista. Não é um ataque — o Notion é um produto genuinamente bom para aquilo para o qual foi criado. É um texto sobre o momento específico em que uma "wiki boa" deixa de ser uma "boa documentação" e sobre como perceber esse momento antes de ter 400 páginas e uma equipe de vendas que precisa que a documentação realmente tenha uma boa classificação.

Onde o Notion ainda se destaca?#

Antes das reclamações, a parte honesta.

O Notion é a melhor ferramenta que já usei para pensamento colaborativo. Documentos de estratégia, notas de reuniões, RFCs em rascunho, especificações de produtos sendo debatidas por quatro pessoas nos comentários — o Notion é a escolha certa. O modelo de blocos, as visualizações de banco de dados, os bancos de dados incorporados, as menções vinculadas, o fato de que qualquer pessoa não técnica pode editar sem quebrar nada — tudo isso é real e difícil de replicar.

Se seus documentos vivem inteiramente dentro da empresa e nunca precisam disputar a atenção de um desconhecido no Google, o Notion está ótimo. Se seu público é formado por quarenta pessoas que têm acesso ao seu Notion, esta publicação não se aplica a você. Feche a aba e vá escrever algo útil.

O restante desta publicação trata do momento em que os documentos saem do prédio.

1. A pesquisa são dois problemas diferentes e o Notion resolve um#

A pesquisa interna do Notion é excelente. Cmd+K, correspondência difusa entre títulos, acesso direto à página. Essa é a pesquisa com a qual os engenheiros se preocupam, e o Notion a desenvolveu bem.

A pesquisa com a qual os clientes se preocupam está no Google, no ChatGPT e no Perplexity. E, nessa pesquisa, o Notion é hostil por padrão. As páginas são carregadas via JavaScript, o HTML fica praticamente vazio até que o React seja hidratado, os links internos passam por redirecionamentos notion.so/<hash>, os títulos geralmente são renderizados com marcação não semântica e as URLs têm a aparência de notion.site/Getting-Started-9f8a3b2c1d4e. O Google consegue rastreá-lo, mas o resultado de SEO é consistentemente pior do que o do mesmo conteúdo em markdown simples em um domínio normal.

Na primeira vez que um concorrente com conteúdo objetivamente pior ficou acima de nós porque escreveu em markdown e publicou um sitemap, senti a lição se consolidar. A documentação voltada para os clientes é uma superfície de SEO. Ela precisa ser tratada como tal. Um wiki não é uma superfície de SEO.

2. Controle de versão que não é controle de versão#

O Notion tem histórico de páginas. Ele não é o git. A diferença importa mais do que eu esperava.

Não consigo comparar duas versões de um documento em uma revisão de código. Não posso perguntar "o que mudou na seção de autenticação entre a v1.4 e a v1.5?" e obter uma resposta clara. Não posso colocar uma alteração na documentação na mesma solicitação de pull que a alteração de código que ela documenta, então a documentação está sempre um pouco atrasada. Não posso pedir a um engenheiro júnior que atualize a referência da API como parte da mesma solicitação de pull que disponibiliza a API, porque a documentação vive em um sistema diferente, com permissões diferentes e um modelo mental diferente.

O resultado é a defasagem da documentação. O código é disponibilizado na segunda-feira, o documento é atualizado na quinta-feira e, na quarta-feira, um cliente lê a versão antiga e abre um chamado de suporte. Multiplique isso por cada lançamento. A solução não é "lembrar as pessoas de atualizar o Notion". A solução é colocar a documentação junto do código, para que "o código foi disponibilizado, mas a documentação não" seja algo sobre o qual as ferramentas de comparação possam alertar.

Quando passei a ter a documentação em um repositório com modelos de solicitações de pull, as atualizações da documentação começaram a fazer parte da definição de concluído, e não ser algo deixado para depois. Essa única mudança no fluxo de trabalho contribuiu mais para manter a documentação atualizada do que qualquer ferramenta.

3. Multilingue não é uma funcionalidade, é uma arquitetura#

Tentamos internacionalizar nossa documentação do Notion uma vez. O plano era razoável: duplicar o espaço de trabalho, traduzir e criar um link a partir de um seletor de idioma. Em um mês, ficou impossível de manter.

O verdadeiro custo de uma documentação multilíngue não é a tradução. É o acoplamento entre os idiomas. Quando a versão em inglês muda, todas as traduções ficam desatualizadas, e você precisa de um sistema que saiba disso. Você precisa de:

• Uma fonte canônica para que os tradutores saibam a partir de qual versão estão traduzindo.
• Uma forma de marcar uma tradução como desatualizada quando a fonte for alterada.
• hreflang tags para que o Google saiba que a página em espanhol é a versão em espanhol da página em inglês, e não uma duplicata.
• Uma URL por idioma com caminhos previsíveis (/es/getting-started, /de/getting-started).
• Uma forma de publicar uma tradução parcial — algumas páginas em cinco idiomas, outras em dois — sem quebrar a navegação.

O Notion não faz nada disso. Você acaba com cinco espaços de trabalho desconectados e uma planilha do Google acompanhando o que ficou dessincronizado. A planilha do Google funciona por cerca de três semanas e então todo mundo desiste.

Se você pretende publicar documentação em mais de um idioma, não comece no Notion. O custo da migração cresce linearmente com o número de páginas, e o sofrimento cresce de forma superlinear.

4. Os rastreadores de IA não conseguem ler o seu wiki#

Este é o novo, e aquele que subestimei.

Em 2026, uma parcela significativa das perguntas “como funciona X” nunca chega ao seu site. O utilizador pergunta ao ChatGPT, ao Claude ou ao Perplexity, e a resposta é sintetizada a partir do que quer que esses modelos consigam ver. A Mintlify mediu 30 dias de tráfego nos sites de documentação que aloja — aproximadamente 790 milhões de pedidos — e relatou que os agentes de programação de IA representaram 45,3% de todos os pedidos, com o Claude Code em 25,2% e o Cursor em 18,0% (O estado do tráfego de agentes na documentação, publicado em 3 de abril de 2026). A sua medição de acompanhamento colocou a participação dos agentes em 66% do tráfego em julho de 2026 (Relatório de meio do ano de 2026, publicado em 29 de julho de 2026). Trata-se da frota de um fornecedor, e não de toda a Web, mas é a maior medição publicada do tráfego de agentes para documentação. Os nossos próprios números são menores e estão a evoluir na mesma direção.

Para que um rastreador de IA cite a sua documentação, tem de conseguir lê-la. Isso significa HTML limpo renderizado no servidor, títulos semânticos, um sitemap.xml, idealmente um llms.txt que liste o conteúdo canónico, e um Allow para os principais agentes de utilizador de IA em robots.txt. O Notion não lhe oferece praticamente nada disto. O HTML depende bastante de JavaScript, não existe llms.txt, e a taxa de respostas dos rastreadores de IA é empiricamente baixa.

Se quiser ser citado num mecanismo de respostas, a sua documentação precisa de parecer, para um rastreador, um site de documentação. Não pode parecer uma SPA construída em torno de uma vista de base de dados.

5. O orçamento de desempenho para a documentação é implacável#

Uma página de documentação deve parecer instantânea. Isso não é uma preferência estilística — é uma alavanca de conversão. O usuário está depurando às 2 da manhã e já está frustrado; cada segundo de carregamento é uma oportunidade para ele desistir e abrir um chamado em vez disso.

Execute uma página publicada pelo Notion no Lighthouse. Os números não são bons. O Largest Contentful Paint geralmente fica na faixa de 3 a 5 segundos em uma conexão celular real, o Cumulative Layout Shift é perceptível porque a árvore do React é hidratada em ondas, e o Total Blocking Time é alto porque há muito JavaScript para analisar.

Para um wiki interno, ninguém se importa. Para uma documentação voltada ao cliente que precisa competir com mil outras abas abertas pelo usuário, isso importa muito. Vimos a taxa de rejeição nas páginas de documentação cair significativamente quando migramos para markdown renderizado estaticamente. Esse é um daqueles números que, depois que você vê, não consegue mais ignorar.

6. A dependência é real e se acumula#

O Notion permite exportar. Eu já usei esse recurso. O resultado é uma pasta com arquivos HTML ou Markdown com nomes de arquivo desfigurados, links internos quebrados apontando para URLs notion.so, bancos de dados incorporados que se transformam em tabelas ilegíveis e referências a imagens que apontam para URLs assinadas do S3 que expiram. Exportar 400 páginas e depois corrigir a exportação dá uma semana de trabalho.

A dependência não diz respeito à existência do botão de exportação. Ela diz respeito a saber se os dados exportados estão estruturados o suficiente para serem úteis em outra ferramenta sem precisar fazer uma migração. Por esse critério, as exportações do Notion são fracas. Quanto mais tempo você permanece, mais páginas acumula e mais alto fica o custo da migração. Você só percebe isso quando tenta sair.

O Markdown em um repositório git tem a propriedade oposta. A “exportação” é git clone. Você pode mover o diretório para qualquer outro gerador de site estático, qualquer outra plataforma de documentação ou simplesmente publicá-lo como arquivos brutos. Essa portabilidade é a propriedade mais subestimada que um sistema de documentação pode ter. Ela não parece valiosa até o dia em que você precisa dela — e então vale tudo.

7. Permissões, rascunhos e a separação entre wiki e documentação#

O problema mais profundo é que wikis e documentação são produtos diferentes que, por acaso, parecem iguais no editor.

Uma wiki é para nós. Ela tem rascunhos, páginas inacabadas, seções apenas internas, páginas nas quais dois líderes de equipe discordam nos comentários, runbooks que nunca deveriam ser públicos e uma pasta de "arquivo" que, na verdade, é apenas onde as coisas vão para ser esquecidas. O modelo de permissões é granular porque o público é granular.

A documentação é para eles. Há uma única versão publicada, nenhum estado intermediário, nenhum rascunho visível para os leitores e nenhuma thread de comentários visível no URL público. Os rascunhos ficam nas pull requests, não na árvore de produção. O modelo de permissões é binário — publicado ou não — porque o público é a internet inteira.

O Notion foi criado para o primeiro caso e adaptado para o segundo. Você acaba com um workspace que mistura páginas do manual interno e documentação de APIs voltada para clientes na mesma árvore, e um erro de configuração torna a página errada pública. Já vi isso acontecer em três empresas e quase fiz isso sozinho.

Vale a pena tornar física a fronteira entre "wiki" e "documentação". Sistema diferente, repositório diferente, fluxo de revisão diferente, domínio diferente.

O que usamos em vez disso?#

Para assuntos internos que precisam de comentários, opiniões, rascunhos e bancos de dados inline — documentos de estratégia, RFCs, notas de reuniões, o manual — o Notion ainda é a ferramenta certa. Não paramos de usar o Notion. Paramos de usá-lo para o trabalho errado.

Para documentação voltada aos clientes, os documentos ficam em um repositório git, escritos em markdown, revisados por meio de pull requests e publicados como um site estático. A configuração é deliberadamente simples. Os documentos ficam ao lado do código, então são atualizados no mesmo PR. O histórico do git é o histórico de versões. O repositório é a exportação. O CI verifica os links. O site publicado é renderizado no servidor, com headings adequados, um sitemap, um llms.txt e uma URL por idioma.

Usar Docsbook, Docusaurus, Mintlify, VitePress ou criar sua própria solução com eleventy é uma decisão menor do que parece. A decisão maior vem antes: esses documentos são para a equipe ou para o mundo? Se forem para o mundo, tire-os da wiki e coloque-os em um sistema que os trate como um produto.

Criamos o Docsbook porque queríamos que “repositório git de markdown” estivesse a cinco segundos de distância de “site de documentação publicado com SEO, chat de IA, quinze idiomas e analytics” — sem uma única etapa de CI ou docusaurus.config.js. Essa é a versão desta história em que temos um produto para vender. Também é o caminho honesto que percorremos. Primeiro tentamos o Notion. Depois tentamos o Docusaurus. Acabamos escrevendo o Docsbook porque queríamos a simplicidade do Notion com as propriedades de engenharia de um site de documentação de verdade, e ninguém mais havia criado isso.

O único princípio que vale a pena manter#

Se a sua documentação precisa ser encontrada por pessoas que não trabalham na sua empresa, ela é um produto de SEO e de capacidade de descoberta por IA. Trate-a como tal. Mantenha-a sob controle de versão, renderize-a como HTML, dê a cada idioma uma URL real e certifique-se de que um crawler possa lê-la sem executar seu JavaScript.

Um wiki é para as pessoas que já estão dentro. A documentação é para as pessoas que ainda estão do lado de fora, olhando para dentro. Você tem uma única chance de causar uma boa primeira impressão, e isso geralmente acontece às 2h da manhã, em um celular, enquanto o leitor está irritado. Crie pensando nesse leitor, não na reunião em que o documento foi escrito.

Essa é a lição. Todo o resto é detalhe de implementação.

Comece gratuitamente — sem cartão de crédito

Próximos passos#

• Como hospedar a documentação de um repositório do GitHub — os três caminhos para sair de um wiki
• Guia de SEO para documentação — o problema de pesquisa descrito integralmente na seção 1
• SEO de documentação multilíngue — o ponto de arquitetura da seção 3
• Como fazer sua documentação ser citada pelo ChatGPT — o problema do rastreador da seção 4