Empieza por el contenido, no por la portada
Una demo puede verse excelente y ser incorrecta para tu documentación. Antes de comparar temas, anota qué necesitas publicar: manuales largos, API reference, tutoriales, páginas generadas, versiones, varios idiomas, miles de artículos o una combinación.
Después describe quién escribe. Engineers que editan Markdown en Git tienen necesidades distintas de expertos ocasionales que trabajan en el navegador.
Compara el modelo de contenido
Sphinx es fuerte cuando importan referencias cruzadas, directivas estructuradas, documentos técnicos largos y extensibilidad. MkDocs encaja bien en flujos Markdown-first y estructuras directas. Astro es un framework web centrado en contenido que ofrece más control sobre layouts, content collections tipadas, assets y routing; esa flexibilidad también implica asumir más del producto editorial.
No hay que coronar un ganador, sino ajustar la abstracción al trabajo.
Calcula la superficie de mantenimiento
Cuenta plugins propios, overrides de tema, pasos de build y convenciones internas. Cada personalización será trabajo en una futura actualización. Pregunta no solo “¿podemos personalizarlo?”, sino “¿entenderá el siguiente maintainer por qué lo hicimos?”.
Prototipa los casos difíciles
Construye un spike con una tabla grande, reuse, localización, código, imágenes, redirects, metadatos de búsqueda y una página larga. Prueba con un volumen representativo.
No evalúes un generador solo por la home.
Conserva una salida
Separa la semántica del contenido de la marca específica de un tema. Prefiere Markdown ordinario y componentes definidos a cientos de fragmentos HTML ad hoc. Documenta el schema de metadatos.
Un generador es infraestructura, no identidad. Elige uno que simplifique publicar hoy y permita migrar mañana.
Ejemplo aplicado
Trata «Cómo elegir un generador de documentación sin elegir una religión» como una evaluación pequeña, no como una comparación de listas de funciones. Elige tres muestras reales: una página sencilla, otra con código o datos estructurados y una tercera con navegación, reutilización o localización. Pruébalas con la herramienta o método y anota qué se simplifica y qué nuevo coste de mantenimiento aparece.
Evalúa el trabajo que el equipo repetirá cada semana:
- si la fuente es comprensible para el autor;
- si el revisor puede ver un diff significativo;
- si un fallo de build señala un problema corregible;
- si el contenido puede moverse, localizarse o reutilizarse sin limpieza manual.
Una buena herramienta reduce incertidumbre en autoría, revisión y publicación. Si la complejidad se desplaza a configuración frágil, plugins o a la memoria de una sola persona, ese coste también cuenta.
Lista rápida de revisión editorial
- Empieza por el contenido, no por la portada. Una demo puede verse excelente y ser incorrecta para tu documentación.
- Compara el modelo de contenido. Sphinx es fuerte cuando importan referencias cruzadas, directivas estructuradas, documentos técnicos largos y extensibilidad.
- Calcula la superficie de mantenimiento. Cuenta plugins propios, overrides de tema, pasos de build y convenciones internas.
- Prototipa los casos difíciles. Construye un spike con una tabla grande, reuse, localización, código, imágenes, redirects, metadatos de búsqueda y una página larga.
