Docs como código vs uma plataforma gerenciada: o compromisso de 2026
"Docs como código" — sua documentação vive no Git, é revisada via pull requests, é implantada via CI — é o padrão dominante em empresas lideradas por engenharia. "Plataforma gerenciada" — você faz login, configura e envia — é o padrão dominante em empresas lideradas por design e independentes. Ambos funcionam. Ambos falham de maneiras diferentes.
Este é o compromisso honesto em 2026.
TL;DR#
| Documentos como código | Plataforma gerenciada | |
|---|---|---|
| Onde os documentos vivem | Git | DB da plataforma ou Git |
| Edição | Markdown no IDE, revisão de PR | Editor web ou markdown |
| Implantação | Pipeline de CI/CD | Empurre e esqueça |
| Hospedagem | Sua | Deles |
| Manutenção | Suas horas de engenharia | Horas do fornecedor |
| Recursos de IA | Você constrói ou integra | Integrado |
| Forma de custo | Horas de engenharia | Assinatura |
| Melhor para | Conduzido por engenharia, OSS, personalização profunda | Startups, indie, "envie agora" |
Docsbook é interessante porque é ambos: arquivos fonte no Git (seu repositório), gerenciou todo o resto.
Quando "docs as code" vence#
Três razões pelas quais docs-as-code ainda é o padrão certo:
1. A engenharia já vive no Git#
Se seus escritores de documentação são engenheiros, a sobrecarga cognitiva de usar o Git para documentação é zero. Pull requests, revisão de código, pré-visualizações de branch — todo o fluxo de trabalho de engenharia existente se estende naturalmente.
2. A versionação alinha-se com lançamentos de código#
As alterações de documentação que acompanham as alterações de código pertencem ao mesmo PR. Os revisores veem a alteração da API e a alteração da documentação juntas. O CI testa ambas.
3. É necessária uma personalização pesada#
Se sua documentação precisar de componentes React, extensões de Markdown personalizadas ou um pipeline de construção que gere páginas a partir da sua especificação OpenAPI, docs-as-code com Docusaurus, Nextra ou VitePress é o padrão certo.
Quando "plataforma gerenciada" vence#
Três razões pelas quais a gerenciada vence:
1. Os escritores de documentação não são engenheiros#
Os profissionais de marketing de produtos, membros da equipe de suporte e líderes de CS frequentemente precisam atualizar a documentação. Pedir que eles façam PR de markdown para um repositório Git cria atrito que impede atualizações. Um editor web é mais rápido.
2. Recursos de IA são necessários e sua equipe não os construirá#
Uma plataforma gerenciada que oferece chat de IA, tradução de IA, MCP, llms.txt e análises fornece cada um deles como um interruptor em vez de um projeto. Cada um é um projeto real se você construí-lo: recuperação, um loop de avaliação, um pipeline de tradução com roteamento por local, um armazenamento de eventos. A maioria das equipes não pode justificar nenhum desse trabalho especificamente para documentos.
3. A propriedade de implantação é sobrecarga, não valor#
O trabalho recorrente em um site de documentação auto-hospedado é real, mas não programado: migrações de versão principal, desvio de dependências e versão do Node, falhas de compilação que ninguém possui, busca que precisa de nova aprovação ou re-hospedagem. Nada disso entrega algo que um leitor possa ver.
Calcule a partir do seu próprio repositório em vez de uma média: conte os commits na sua infraestrutura de documentação nos últimos quatro trimestres que não mudaram conteúdo. Esse número é a coisa que uma plataforma gerenciada remove.
O híbrido: Docsbook#
Docsbook é incomum porque não se encaixa perfeitamente em nenhuma das categorias.
- A fonte da verdade é seu repositório GitHub (propriedade docs-as-code)
- Hospedagem, IA, pesquisa, traduções, análises, MCP são gerenciados (propriedade managed-platform)
- Sem pipeline CI/CD, sem
docusaurus.config.js, sem swizzle (propriedade managed-platform) - PRs e revisões funcionam da mesma forma (propriedade docs-as-code)
- Sem bloqueio de fornecedor — seus arquivos permanecem no GitHub quando você sai (propriedade docs-as-code)
Esse padrão é importante porque os modos de falha do docs-as-code puro (carga de implantação) e do gerenciado puro (bloqueio de fornecedor) se cancelam.
Cálculo de custos#
Vamos comparar o custo total de propriedade de 24 meses para uma startup típica de 5 engenheiros.
Documentação pura como código (Docusaurus no Vercel)#
| Item | Custo de 24 meses |
|---|---|
| Hospedagem em um plano pago | Uma fatura recorrente que você não notará |
| Configuração inicial | Horas de engenharia, uma vez |
| Migrações de versão principal | Horas de engenharia, aproximadamente duas vezes em dois anos |
| Manutenção trimestral | Horas de engenharia, recorrente, não programada |
| Construindo chat de IA | Semanas de engenharia, além da continuidade da qualidade de recuperação |
| Executando chat de IA | Armazenamento vetorial, embeddings e chamadas de modelo, mensal |
| Busca (Algolia DocSearch, ou auto-hospedado) | Gratuito se aprovado, caso contrário, uma assinatura ou mais horas |
| Pipeline de tradução | Geralmente ignorado, porque é um projeto em vez de um item |
O lado gerenciado#
| Item de linha | Custo de 24 meses |
|---|---|
| Assinatura ou uso medido | O número do fornecedor — leia na página de preços deles |
| Configuração inicial | Menos de uma hora |
| Manutenção | Nenhuma |
Como realmente executar esta comparação#
Preencha ambas as tabelas com seus próprios números em vez dos nossos. Publicamos deliberadamente nenhum valor em dólares aqui, porque os únicos honestos são os seus: seu nível de hospedagem, o custo carregado de seus engenheiros, seu tráfego.
Duas coisas valem a pena notar uma vez que você as preencheu. Primeiro, as horas de engenharia dominam a coluna de auto-hospedagem, e são as entradas que ninguém orça. Segundo, a linha de tradução está quase sempre vazia do lado da auto-hospedagem — não porque a tradução não tenha valor, mas porque nunca atinge o nível como um projeto, o que significa que a comparação não é equivalente a menos que você diga isso em voz alta.
(Docsbook anteriormente vendia um plano PRO vitalício único; ele não é mais oferecido, e os compradores vitalícios existentes mantêm seus termos originais.)
Quando a matemática de custos se inverte#
Três cenários onde docs-as-code é mais barato:
- Horas de engenharia são gratuitas — você tem um engenheiro especificamente encarregado da plataforma de documentação; seu salário é comprometido independentemente
- OSS com contribuintes da comunidade — PRs da comunidade absorvem a carga de manutenção
- Componentes React personalizados dentro da documentação — você não pode fazer isso em plataformas gerenciadas
Nesses casos, Docusaurus ou VitePress é a resposta certa. Caso contrário, a matemática favorece as gerenciadas.
Bloqueio de fornecedor: como avaliar#
Três perguntas a fazer a qualquer plataforma gerenciada:
- Posso exportar meu conteúdo como markdown simples agora? Se sim, o bloqueio é baixo.
- Os URLs sobreviverão se eu me mudar? A maioria permite a preservação de URLs; alguns não.
- O que acontece com meu domínio personalizado se eu cancelar? Ele deve ser recuperável.
Docsbook se sai bem em todos os três: os arquivos estão no seu repositório GitHub (exportar = git clone), os URLs correspondem aos caminhos dos arquivos (preservar = redirecionamentos), o domínio personalizado é um registro DNS que você controla.
GitBook se sai mal no primeiro (conteúdo em seu banco de dados), bem nos outros. Mintlify se sai bem em todos os três.
Regras de decisão#
- Conduzido por engenharia, OSS, com muita personalização → docs como código (Docusaurus, VitePress, Nextra)
- Indie, startup, "enviar agora" → plataforma gerenciada (Docsbook, Mintlify)
- Empresa com 30+ editores → empresa gerenciada (GitBook)
- Quer o híbrido → Docsbook (fonte Git, gerenciado o resto)
Leitura relacionada#
- Melhores plataformas de documentação para startups em 2026
- Docusaurus vs Docsbook em 2026
- Comparação de hospedagem de documentação gratuita
Docsbook é o híbrido: a fonte permanece no Git, enquanto IA, SEO, traduções e MCP são gerenciados. A precificação é medida com base no uso de IA, em vez de ser vendida como um nível — números atuais em docsbook.io/pricing.