Comece pelo conteúdo, não pela home
Uma demo bonita pode ser errada para sua documentação. Antes de comparar temas, liste o que precisa publicar: manuais longos, API reference, tutoriais, páginas geradas, versões, vários idiomas, milhares de artigos ou uma combinação.
Depois descreva quem escreve. Engineers editando Markdown em Git têm necessidades diferentes de especialistas ocasionais usando o navegador.
Compare o modelo de conteúdo
Sphinx é forte em cross-references, diretivas estruturadas, documentos técnicos longos e extensibilidade. MkDocs funciona bem em fluxos Markdown-first. Astro é um framework web content-focused que oferece mais controle sobre layouts, typed content collections, assets e routing; essa flexibilidade também significa assumir mais do produto editorial.
O objetivo não é eleger um vencedor, e sim combinar abstração e trabalho.
Calcule a superfície de manutenção
Conte plugins customizados, overrides de tema, etapas de build e convenções internas. Cada customização será trabalho numa atualização futura. Pergunte não só “podemos alterar isso?”, mas “o próximo mantenedor entenderá por quê?”.
Prototipe os casos difíceis
Faça um spike com tabela grande, reuse, localização, código, imagens, redirects, metadados de busca e página longa. Teste com volume representativo.
Não avalie um gerador apenas pela primeira página.
Preserve uma saída
Separe a semântica do conteúdo da marcação específica do tema. Prefira Markdown comum e componentes bem definidos a centenas de fragmentos HTML ad hoc. Documente o schema de metadados.
Gerador é infraestrutura, não identidade. Escolha um que facilite publicar hoje e deixe uma rota razoável de migração amanhã.
Exemplo aplicado
Trate “Como escolher um gerador de documentação sem escolher uma religião” como uma avaliação pequena, não como comparação de listas de recursos. Escolha três amostras reais: uma página simples, uma com código ou dados estruturados e outra com navegação, reutilização ou localização. Teste todas com a ferramenta ou método e anote o que ficou mais fácil e qual novo custo de manutenção apareceu.
Avalie o trabalho repetido da equipe:
- se a fonte é compreensível para o autor;
- se o revisor enxerga um diff significativo;
- se o build aponta um problema que pode ser corrigido;
- se o conteúdo pode ser movido, localizado e reutilizado sem limpeza manual.
Uma boa ferramenta reduz incerteza em autoria, revisão e publicação. Se a complexidade apenas migra para configuração frágil, plugins ou memória de uma pessoa, esse custo também faz parte da decisão.
Checklist editorial rápido
- Comece pelo conteúdo, não pela home. Uma demo bonita pode ser errada para sua documentação.
- Compare o modelo de conteúdo. Sphinx é forte em cross-references, diretivas estruturadas, documentos técnicos longos e extensibilidade.
- Calcule a superfície de manutenção. Conte plugins customizados, overrides de tema, etapas de build e convenções internas.
- Prototipe os casos difíceis. Faça um spike com tabela grande, reuse, localização, código, imagens, redirects, metadados de busca e página longa.
