Cómo crear un sitio de documentación técnica sin código
Para crear un sitio de documentación sin código, define primero el árbol de secciones y el formato de una página, y descríbelo en texto. Zugo construye la navegación lateral, el buscador y las páginas a partir de esa descripción, y publica el resultado tras comprobarlo en un entorno de prueba.
La documentación tiene una particularidad frente a otros sitios: casi todo su valor está en la organización, no en el diseño. Un lector con un problema concreto no navega, busca, y si no encuentra en dos intentos abre un ticket de soporte. Esta guía se centra en construir un sitio que evite ese segundo intento.
¿Cómo se organiza un sitio de documentación?
Hay tres bloques que casi cualquier documentación necesita, y mezclarlos es el error más frecuente. El primero es la guía de inicio: el camino más corto desde cero hasta algo funcionando. El segundo son las guías de tarea, que responden a "cómo hago X". El tercero es la referencia, que responde a "qué hace exactamente este parámetro".
Los tres tienen lectores distintos y no se leen igual. La guía de inicio se lee entera una vez. Las guías de tarea se leen a saltos. La referencia no se lee: se consulta. Si los pones en la misma sección, el que consulta tiene que atravesar prosa introductoria y el que empieza se pierde entre tablas de parámetros.
La navegación lateral debe reflejar esa separación de forma visible, con tres grupos y no con una lista plana de veinte enlaces. Y cada página necesita un título que sea la pregunta del lector, no el nombre interno de la función. "Cómo invitar a un compañero" se encuentra. "Gestión de miembros del espacio de trabajo" no.
¿Qué debe decir el prompt?
Al constructor le das la estructura y el formato de página, no el contenido completo. Con eso obtienes un esqueleto que puedes rellenar durante meses sin rediseñar nada:
Crea un sitio de documentación para [producto].
Navegación lateral con tres grupos:
1. Primeros pasos: [lista de páginas]
2. Guías: [lista de páginas]
3. Referencia: [lista de páginas]
Cada página: título en forma de pregunta o tarea, resumen de
2 frases arriba, cuerpo con encabezados, bloques de código con
resaltado y copia al portapapeles, y bloques de aviso
(nota, atención, importante).
Cabecera fija con buscador, enlace al producto y selector de
tema claro y oscuro.
Índice de contenidos a la derecha en cada página.
Tono: instrucciones directas, segunda persona, sin marketing.
Pide el buscador y el índice lateral desde la primera construcción. Los dos son sencillos de incluir de entrada y molestos de retro-encajar cuando ya hay cuarenta páginas escritas y la maquetación se ha asentado.
Zugo trae 25 plantillas listas. Ninguna sustituye a una estructura pensada por ti, pero partir de una con navegación lateral ahorra la primera iteración.
¿Un sitio propio o una herramienta de documentación ya hecha?
No todo producto necesita construirse su documentación. La tabla compara las tres opciones reales para que decidas antes de escribir el prompt.
| Opción | A quién le encaja | Qué te cuesta |
|---|---|---|
| Sitio construido con IA en tu dominio | Producto pequeño o mediano, documentación estable | Cada cambio pasa por una edición del sitio |
| Documentación en el repositorio, generada desde Markdown | Equipos donde los desarrolladores escriben los docs | Configuración inicial y flujo de trabajo con Git |
| Herramienta alojada de documentación | Equipos que quieren buscador y versiones sin montar nada | Cuota mensual y dominio de un tercero delante |
Si tu documentación la escriben desarrolladores dentro de las mismas ramas donde cambia el código, la segunda fila es honestamente mejor: el docs-as-code está diseñado para eso y hace cosas que un constructor no hace. Si la escribe una persona de producto o de soporte, la primera fila gana, porque editar en lenguaje natural es más rápido que abrir una pull request.
Con Zugo también hay salida hacia la segunda opción: la exportación a GitHub te entrega el repositorio real, y a partir de ahí un desarrollador lo lleva donde quiera. Está explicado en cómo exportar el código.
¿Cómo se añaden y actualizan páginas después?
En Zugo se describe el cambio: "añade una página en Guías titulada Cómo conectar el webhook, con tres pasos numerados, un bloque de código de ejemplo y un aviso de que la URL debe ser https". La página aparece en el grupo correcto y con el formato del resto.
Cada edición cuesta 3 créditos y vuelve a verificarse antes de entregarse, lo que tiene un efecto útil: no publicas por accidente una página que no carga porque un bloque de código quedó mal cerrado. Reduce el riesgo, no lo elimina, y la revisión del contenido sigue siendo tuya.
Si tu documentación cambia a diario, editar así se hará pesado. Dos salidas razonables: agrupar los cambios de la semana en una sola edición, o mover el contenido a Supabase y que el sitio lo lea, con lo que publicar pasa a ser añadir un registro. La segunda opción es más trabajo inicial y compensa cuando escriben varias personas.
¿Qué hacer con las versiones y los idiomas?
Las versiones son la trampa clásica de la documentación. Antes de duplicar nada, pregúntate si tus usuarios usan de verdad versiones antiguas. En un servicio en la nube donde todo el mundo está en la última versión, mantener un selector de versiones es trabajo puro sin beneficio.
Cuando sí hacen falta, la forma barata es documentar solo la versión actual y añadir avisos en las páginas afectadas: "disponible desde la versión 2.3". Duplicar el árbol completo por versión multiplica el mantenimiento y es la razón por la que tantas documentaciones tienen ramas desactualizadas.
Con los idiomas pasa algo parecido. Traducir la guía de inicio y dejar la referencia en inglés es una decisión defendible y muy común. Traducir todo y no mantenerlo produce documentación que miente en un idioma, que es peor que no tenerla.
¿Cuánto cuesta y dónde vive el sitio?
Zugo cobra por acción en créditos. La construcción cuesta 6 créditos y cada edición 3. Una documentación es por naturaleza multipágina, así que el tramo aplicable suele ser el de plataforma: 12 créditos por las tres primeras páginas y 3 por cada página adicional. Una construcción sencilla tarda alrededor de un minuto; una plataforma multipágina con varias secciones tarda algunos minutos.
El plan Free da 5 créditos, suficiente para curiosear. Un sitio de documentación real empieza en Pro: 25 dólares al mes con 200 créditos. Business son 99 dólares al mes. El modo Hi-Fi duplica el coste por acción: 12 construir, 6 editar.
Al publicar, el sitio queda en una dirección del tipo tudocs.zugo.run, y conectar tu propio dominio está soportado. Para documentación conviene hacerlo pronto: docs.tuproducto.com es lo que la gente enlaza desde tickets, foros y respuestas, y cambiar esa dirección más adelante rompe enlaces que ya no controlas.
¿Dónde se queda corto un constructor con IA en documentación?
Tres límites honestos.
La documentación generada desde el código no sale de aquí. Si tu referencia de API se genera a partir de anotaciones o de un esquema OpenAPI, quieres una herramienta de generación automática, no un constructor conversacional.
El buscador tiene techo. Un buscador por título y texto funciona bien con decenas de páginas. Con cientos y con sinónimos y relevancia, necesitas un servicio de búsqueda dedicado, y eso es integración de desarrollo.
El contenido sigue siendo el trabajo. El sitio se construye en una tarde. Escribir treinta páginas correctas, probadas y actualizadas es el proyecto real, y no hay atajo.
Para un producto que necesita documentación clara en su propio dominio sin dedicarle una semana de desarrollo, el alcance encaja. Si además quieres publicar novedades con fecha, la guía sobre cómo crear un blog cubre esa parte. Cuando tengas el árbol de secciones decidido, empieza en zugo.dev.