Objetivos de diseño para una landing estilo documentación

Una landing estilo documentación es lo que sucede cuando respetas el tiempo del lector. El objetivo no es hipnotizar a alguien con degradados hasta que haga clic en un botón. El objetivo es permitir que se auto-califique rápido: «¿Es esto para mí?» y «¿Funcionará en mi entorno?».

Si alguna vez estuviste de guardia mientras un experimento de marketing enviaba un video de hero de 5 MB, ya entiendes la premisa: la fiabilidad es una característica, y una landing forma parte del sistema. Participa en tus SLOs aunque nadie lo admita en la reunión de planificación.

Qué significa realmente «estilo documentación»

Estilo documentación no es solo tipografía. Es un contrato de información. Declaras qué hace el producto, cómo se comporta, cuánto cuesta y qué no hace—sin obligar al lector a descifrar metáforas de marketing.

Específicamente:

• La navegación es predecible: un TOC, enlaces ancla y títulos estables.
• Los precios son explícitos: qué incluye, qué no, qué pasa en los límites.
• La FAQ está redactada como si soporte ya hubiera recibido el ticket.
• El rendimiento se trata como infraestructura presupuestada, no como una sensación.

Restricciones que mejoran la página

HTML/CSS puro te da restricciones que te salvan de ti mismo. Sin cadena de build, sin deriva de dependencias, sin «alguien actualizó el router y la landing se rompió». Tu superficie de riesgo se reduce. La historia de despliegue pasa a ser: sube un archivo, configura headers de caché, verifica.

La restricción también es una herramienta de diseño. Cuando no puedes confiar en un componente de framework para todo, escribes menos y eliges con más cuidado: menos fuentes, menos layouts, menos puntos de ruptura, menos milagros.

Estructura HTML que escala sin drama

Las landing pages se pudren cuando crecen. Alguien añade otra sección, luego una barra lateral, luego un «CTA flotante», y de repente tus encabezados están desordenados y tu CSS es un yacimiento arqueológico.

La solución no es un framework. La solución es estructura: HTML semántico, nombres de clase predecibles y un layout que degrade con gracia.

Usa hitos semánticos para que tu página tenga un manual de operación

Usa <header>, <nav>, <main>, <section> y <footer> como si importara. Una página estilo documentación debe poder navegarse sin ratón y sin adivinar dónde escondió el autor el contenido.

Los encabezados son una API: no los rompas

Mantén un solo <h1>. Usa <h2> para secciones principales: Funciones, Precios, FAQ y tus secciones operativas como diagnósticos y errores. Dentro de cada una, <h3> para subtemas. Esto importa para accesibilidad, SEO y para las personas que escanean la página a 1.7 segundos por párrafo.

Haz que el TOC sea real, no decorativo

Un índice con enlaces ancla hace tres cosas: reduce el rebote porque la gente puede saltar a la pregunta que buscaba; hace que la página se sienta «documentada»; y te da objetivos estables para links internos desde correos, tickets y chats.

El truco es la estabilidad. No bases anclas en contenido que cambia semanalmente. Usa ids que sobrevivan a ediciones. Si debes renombrar encabezados, mantiene los ids estables salvo que estés listo para soportar enlaces antiguos.

FAQ en CSS puro: usa details/summary con intención

El elemento details es el héroe silencioso de la interactividad «sin JS». Es accesible por teclado y funciona sin scripts. Estílalo ligeramente. No lo conviertas en una imitación frágil de un acordeón JavaScript.

Dos reglas que evitan el 80% de los bugs de layout

• Define dimensiones de imágenes (o relación de aspecto) para que el layout no salte. CLS es un impuesto SEO y un impuesto a la confianza del usuario.
• Usa contenedores con max-width. Full-bleed está bien para fondos. El texto necesita una medida legible, no una pista de aterrizaje.

Un chiste corto, porque nos lo ganamos: CSS es fácil hasta que deja de serlo, y entonces se vuelve un debate religioso con peores herramientas.

Sección de funciones que responde objeciones reales

Las funciones no son una lista de compras. Son refutaciones a objeciones. En una página estilo documentación, cada función debe explicar: qué hace, qué reemplaza y qué modo de fallo evita. Si no cambia una decisión, es decoración.

Copy de funciones que no envejece mal

Evita afirmaciones versionadas como «el más rápido del mercado» a menos que estés preparado para volver a probarlo semanalmente. Prefiere afirmaciones que puedas mantener verdaderas con procesos: «static-first», «sin JavaScript requerido», «hitos accesibles», «caché predecible».

Aquí es donde la mentalidad ops ayuda a marketing. Las promesas se vuelven restricciones. Las restricciones se vuelven fiabilidad.

Precios que evitan tickets de soporte

Los precios son operativos. Si son vagos, lo pagarás en llamadas de preventa, reembolsos, correos furiosos y ingenieros arrastrados a «preguntas rápidas». Una sección de precios estilo documentación debe leerse como un adelanto de contrato: qué obtienes, qué no y qué sucede cuando alcanzas límites.

Reglas de diseño de precios que deberías adoptar

Segundo chiste corto (y ese es el cupo): «Ilimitado» suele significar «reuniones ilimitadas», y te facturarán en atención.

FAQ que reduce el ruido de ventas

Tu FAQ no es un vertedero de preguntas aleatorias. Es un escudo. Bloquea las conversaciones previsibles de «¿qué pasa con…?» antes de que se conviertan en invitaciones de calendario. Mantén las respuestas concisas, comprobables y redactadas como si ya hubieras conocido a un cliente.

Hechos e historia: por qué «solo HTML/CSS» sigue ganando

Un poco de contexto te ayuda a argumentar a favor de la simplicidad en salas que aman la complejidad. Aquí hay hechos concretos que importan cuando eliges HTML/CSS puro para una landing.

Esa frase debe estar en la pared cerca de tu petición de «añadamos un tercer script de analytics». Si no puedes explicar el modo de fallo y el plan de rollback, no estás enviando una función; estás enviando una sorpresa.

Tareas prácticas para operadores: comandos, salidas, decisiones

Esta es la parte que la mayoría de las landing pages no incluye: cómo operar la cosa como si importara. A continuación hay tareas prácticas que puedes ejecutar en un host Linux que sirva tu HTML estático, con comandos, salidas realistas y qué decisión tomar según ellas.

Asume que Nginx sirve /var/www/landing, y que despliegas a un host llamado server. Ajusta rutas y nombres según tu entorno, pero mantén la lógica de decisión.

Tarea 1: Validar que el HTML realmente se está sirviendo

cr0x@server:~$ curl -I http://127.0.0.1/
HTTP/1.1 200 OK
Server: nginx/1.24.0
Content-Type: text/html
Content-Length: 48231
Last-Modified: Mon, 29 Dec 2025 10:15:44 GMT
ETag: "67713d10-bc67"
Accept-Ranges: bytes

Qué significa: Estás recibiendo un 200 y el contenido es HTML. ETag y Last-Modified existen, así que las solicitudes condicionales pueden funcionar.

Decisión: Si esto no es 200, arregla el routing/virtual host antes de perseguir fantasmas de rendimiento. Si Content-Type es incorrecto, tu configuración del servidor o los archivos están mal.

Tarea 2: Revisar headers de caché para HTML (de corta duración por diseño)

cr0x@server:~$ curl -I http://127.0.0.1/ | grep -i cache-control
Cache-Control: public, max-age=60

Qué significa: El HTML está cacheado 60 segundos. Es un compromiso común: evita thrash y permite que las actualizaciones aparezcan rápido.

Decisión: Si el HTML está cacheado por horas, enviarás correcciones lentamente y confundirás a usuarios. Si no está cacheado, tu origen trabajará más de lo necesario.

Tarea 3: Revisar headers de caché para assets inmutables (larga duración)

cr0x@server:~$ curl -I http://127.0.0.1/assets/app.3f2c1a9e.css | egrep -i 'cache-control|content-type'
Content-Type: text/css
Cache-Control: public, max-age=31536000, immutable

Qué significa: El CSS está cacheado por un año y marcado como immutable, lo cual es correcto solo si el nombre de archivo contiene hash de contenido.

Decisión: Si no tienes nombres con hash, no uses immutable. Crearás tickets de «¿por qué no se actualiza el estilo?» para ti mismo.

Tarea 4: Confirmar que gzip/brotli es efectivo (los bytes cuentan)

cr0x@server:~$ curl -I -H 'Accept-Encoding: gzip' http://127.0.0.1/ | egrep -i 'content-encoding|content-length'
Content-Encoding: gzip
Content-Length: 8421

Qué significa: El HTML está comprimido. Menor transferencia, renderizado inicial más rápido en redes lentas.

Decisión: Si falta compresión, habilítala para tipos de texto. Si está habilitada pero Content-Length sigue enorme, revisa contenido ya comprimido o mala configuración.

Tarea 5: Verificar que no sirves 404 accidentales (rutas de assets rotas)

cr0x@server:~$ tail -n 20 /var/log/nginx/access.log
127.0.0.1 - - [29/Dec/2025:10:27:05 +0000] "GET /assets/app.3f2c1a9e.css HTTP/1.1" 200 21844 "-" "curl/8.5.0"
127.0.0.1 - - [29/Dec/2025:10:27:06 +0000] "GET /assets/hero.webp HTTP/1.1" 200 148920 "-" "curl/8.5.0"
127.0.0.1 - - [29/Dec/2025:10:27:07 +0000] "GET /assets/font.woff2 HTTP/1.1" 404 153 "-" "curl/8.5.0"

Qué significa: Se está solicitando una fuente faltante. Eso puede causar FOIT/FOUT, saltos de layout y renderizado feo.

Decisión: Arregla la ruta o elimina la referencia. No ignores 404s «porque la página funciona la mayor parte del tiempo». Los 404s también son problemas de rendimiento.

Tarea 6: Detectar requests lentos en el origen (tiempos en Nginx)

cr0x@server:~$ awk '{print $NF}' /var/log/nginx/access.log | tail -n 5
0.001
0.002
0.001
0.089
0.001

Qué significa: Una solicitud tardó 89 ms en Nginx. Si eso es común, tienes IO, CPU o lentitud upstream.

Decisión: Si el contenido estático es lento de servir localmente, revisa latencia de disco, sistema de archivos y si estás proxyando contenido dinámico por accidente.

Tarea 7: Confirmar que la configuración de Nginx es la que crees

cr0x@server:~$ nginx -T 2>/dev/null | sed -n '1,40p'
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
# configuration file /etc/nginx/nginx.conf:
user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

Qué significa: La configuración cargada es válida y estás viendo la config que se está ejecutando.

Decisión: Si no puedes reproducir un header o comportamiento de routing, comienza aquí. Muchos problemas «misteriosos» son «archivo equivocado editado».

Tarea 8: Revisar TLS y validez del certificado (no esperes a la alerta)

cr0x@server:~$ echo | openssl s_client -servername example.com -connect example.com:443 2>/dev/null | openssl x509 -noout -dates
notBefore=Dec 10 00:00:00 2025 GMT
notAfter=Mar 10 23:59:59 2026 GMT

Qué significa: Las fechas del certificado son visibles. Si estás cerca de notAfter, pronto tendrás una interrupción muy pública.

Decisión: Renueva temprano, automatiza renovaciones y monitorea expiración. Las caídas por certificados son las más evitables, por eso son tan embarazosas.

Tarea 9: Revisar tiempo de resolución DNS (latencia antes de conectar)

cr0x@server:~$ dig example.com +stats | egrep 'Query time|SERVER'
;; Query time: 42 msec
;; SERVER: 127.0.0.53#53(127.0.0.53) (UDP)

Qué significa: La consulta DNS tardó 42 ms localmente. Para usuarios finales, el DNS puede ser peor. DNS lento infla la percepción de lentitud.

Decisión: Si DNS es lento, investiga resolvers, caché y salud de registros. No culpes al CSS por problemas de DNS.

Tarea 10: Inspeccionar tamaños de assets en disco (ejecución del presupuesto)

cr0x@server:~$ du -h /var/www/landing/assets | sort -h | tail -n 8
56K	/var/www/landing/assets/app.3f2c1a9e.css
148K	/var/www/landing/assets/hero.webp
320K	/var/www/landing/assets/logo.svg
1.2M	/var/www/landing/assets/screenshot.png

Qué significa: Una captura PNG pesa 1.2 MB. Es candidata a conversión a WebP/AVIF y a redimensionado.

Decisión: Define un presupuesto de tamaño por asset y aplícalo en revisión. Si una imagen supera unos cientos de KB, debe justificarse.

Tarea 11: Confirmar que las referencias HTML son correctas (sin hashes faltantes)

cr0x@server:~$ grep -nE 'assets/.*\.(css|js|png|webp|woff2)' /var/www/landing/index.html | head
34:  <link rel="stylesheet" href="/assets/app.3f2c1a9e.css">
66:  <img src="/assets/hero.webp" width="1200" height="700" alt="...">

Qué significa: Tu página referencia assets con hash y las imágenes tienen dimensiones explícitas. Bien.

Decisión: Si los assets no tienen hash y están cacheados por largo tiempo, arregla el pipeline. Si las imágenes carecen de dimensiones, añádelas para reducir CLS.

Tarea 12: Revisar límites de archivos abiertos y salud de workers (el estático también necesita higiene del SO)

cr0x@server:~$ cat /proc/$(pgrep -n nginx)/limits | egrep 'Max open files|Max processes'
Max open files            1024                 1024                 files
Max processes             62967                62967                processes

Qué significa: Nginx puede abrir solo 1024 archivos por proceso worker. Bajo carga, esto puede causar errores o latencia.

Decisión: Si esperas alta concurrencia, aumenta límites vía overrides de systemd y configuración de Nginx. Las páginas estáticas aún pueden sufrir DoS por popularidad.

Tarea 13: Validar que tu CDN (o proxy inverso) realmente cachea

cr0x@server:~$ curl -I https://example.com/ | egrep -i 'age|via|x-cache|cache-control'
cache-control: public, max-age=60
via: 1.1 varnish
age: 38
x-cache: HIT

Qué significa: La respuesta se sirve desde caché (HIT) y tiene una Age de 38 segundos.

Decisión: Si siempre ves MISS, estás pagando por un CDN que no usas. Arregla keys de caché, cookies o headers que impidan el caching.

Tarea 14: Detectar efectividad de compresión en assets (no comprimas lo incomprimible)

cr0x@server:~$ curl -I -H 'Accept-Encoding: gzip' http://127.0.0.1/assets/hero.webp | egrep -i 'content-encoding|content-type'
Content-Type: image/webp

Qué significa: No hay Content-Encoding, lo cual es correcto. WebP ya está comprimido; gzippinglo gasta CPU sin beneficio.

Decisión: Comprime texto; no gastes ciclos en imágenes ya comprimidas.

Tarea 15: Confirmar nivel de logs y visibilidad de errores (no volar a ciegas)

cr0x@server:~$ tail -n 20 /var/log/nginx/error.log
2025/12/29 10:27:07 [error] 1402#1402: *91 open() "/var/www/landing/assets/font.woff2" failed (2: No such file or directory), client: 127.0.0.1, server: _, request: "GET /assets/font.woff2 HTTP/1.1", host: "127.0.0.1"

Qué significa: Evidencia clara de lo que falta y dónde Nginx buscó.

Decisión: Arregla la ruta del archivo y redeploya. Además añade una verificación en el deploy que falle si faltan assets referenciados.

Guía de diagnóstico rápido

Si la landing está lenta o rota, no quieres una sesión de lluvia de ideas. Quieres una secuencia que encuentre el cuello de botella rápido. Esta guía está ordenada para eliminar clases enteras de problemas con rapidez.

Primero: confirma qué significa «lento» y dónde

• ¿Es global o local? Prueba desde el propio servidor (curl a localhost) y desde una red cliente.
• ¿Es primer byte o render? Si TTFB es alto, mira origen/proxy. Si TTFB está bien pero la página «se siente» lenta, revisa payload y render (imágenes, fuentes).
• ¿Es consistente o esporádico? Lo esporádico implica contención de recursos, rate limiting o churn de caché.

Segundo: descarta errores de caché y routing

• Revisa 404s en logs de acceso/error. Assets rotos parecen «lentos» por reintentos y comportamientos fallback.
• Inspecciona Cache-Control y si el CDN está devolviendo HITs.
• Verifica que estás sirviendo el build correcto (sin versiones mezcladas entre hosts).

Tercero: busca los culpables clásicos de rendimiento

• Imágenes: el asset más grande domina. Redimensiona, convierte y lazy-load debajo del pliegue si corresponde.
• Fuentes: las fuentes que cargan tarde pueden bloquear el render o causar shift. Prefiere fuentes del sistema o WOFF2 subconfigurado.
• Demasiadas requests: cada request cuesta latencia. Incrusta CSS crítico pequeño, pero no lo inlines todo y hinches el HTML.

Cuarto: verifica que SO y disco no sean el cuello de botella oculto

• Si Nginx es lento sirviendo archivos locales, revisa latencia de disco, límites de archivos y saturación de CPU.
• Si TLS tarda en el handshake, revisa cadena de certificados, CPU y si HTTP/2 está habilitado.

Errores comunes: síntomas → causa raíz → solución

La mayoría de fallos en las landing pages no son misteriosos. Son patrones recurrentes con síntomas específicos. Aquí están los que veo repetidamente cuando equipos envían «contenido estático simple» y luego lo vuelven complejo por accidente.

Tres micro-historias corporativas desde las trincheras

Estas están anonimizadas, son plausibles y dolorosamente familiares. Cada una tiene una lección que puedes aplicar a tu propia landing HTML/CSS puro antes de que el pager te la aplique a ti.

Listas de verificación / plan paso a paso

Este es el plan que entregaría a un equipo que quiere una landing estilo documentación en HTML/CSS puro y que desea que se mantenga sana después de enviarla. Síguelo en orden. No lo «optimices» hasta tener datos.

Paso 1: Estructura de contenido antes del estilo

• Escribe el H1 como la promesa que puedes cumplir.
• Redacta un lead de 1–2 párrafos que nombre un dolor real.
• Crea un TOC con anclas estables.
• Escribe funciones como objeciones respondidas, no adjetivos.
• Escribe precios como un extracto de contrato: inclusiones, exclusiones, límites.
• Escribe FAQ a partir de tickets reales y conversaciones de ventas.

Paso 2: CSS que se comporta bajo cambios

• Usa un contenedor con max-width y longitud de línea legible.
• Usa clamp() para tipografía y evita sopa de breakpoints.
• Prefiere grid/flex con puntos de quiebre simples.
• Evita resets globales que sorprendan elementos de formulario y herramientas de accesibilidad.
• Mantén nombres de clase descriptivos; evita anidamientos ingeniosos que tu yo futuro no pueda depurar.

Paso 3: Política de assets (donde vive el rendimiento)

• Decide: fuentes del sistema primero; fuentes personalizadas solo con justificación escrita.
• Define un presupuesto de imágenes por sección y aplícalo en revisión.
• Usa WebP/AVIF para imágenes grandes; conserva SVG para logos/ilustraciones que lo beneficien.
• Hashea nombres de archivo para assets cacheables.

Paso 4: Despliegue que evita estado parcial

Despliega páginas estáticas como despliegas binarios: de forma atómica y con verificación. Un patrón limpio es directorios de release + swap de symlink.

cr0x@server:~$ sudo mkdir -p /var/www/landing/releases/2025-12-29_1015/assets
cr0x@server:~$ sudo rsync -a ./site/ /var/www/landing/releases/2025-12-29_1015/
cr0x@server:~$ sudo ln -sfn /var/www/landing/releases/2025-12-29_1015 /var/www/landing/current
cr0x@server:~$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
cr0x@server:~$ sudo systemctl reload nginx

Qué significa la salida: La config es válida; el reload es seguro. El swap de symlink es atómico, así los usuarios nunca ven un estado medio desplegado.

Decisión: Si nginx -t falla, no recargues. Arregla la config y vuelve a probar. Si no puedes explicar los modos de fallo de tu deploy, estás desplegando esperanza.

Paso 5: Puertas de verificación (simples pero estrictas)

• Ejecuta curl -I y verifica headers de caché.
• Descarga el HTML y haz grep de referencias de assets esperadas.
• Escanea logs por 404s inmediatamente después del deploy.
• Revisa expiración de TLS si cambiaste dominios o certificados.

Paso 6: Responsabilidad operativa

Asigna un responsable del presupuesto de rendimiento y del proceso de despliegue. «Marketing lo posee» es como terminas con 12 trackers y un hero con autoplay. «Ingeniería lo posee» es cómo obtienes una página que nunca se envía. La respuesta correcta es compartida: marketing posee el contenido, ingeniería posee las restricciones de entrega.

Próximos pasos

Si quieres una landing estilo documentación que funcione en producción, haz tres cosas esta semana:

1. Congela la estructura: secciones semánticas, anclas estables y una FAQ que responda preguntas reales.
2. Establece presupuestos: tamaños de imagen, número de fuentes y reglas de caché para HTML vs assets.
3. Haz despliegues atómicos: directorios de release y swap de symlink, más chequeo post-deploy de 404s y headers.

HTML/CSS puro no es nostalgia. Es una decisión para enviar menos riesgo. Siempre puedes añadir complejidad después. Quitarla es la parte que duele.