Cómo escribir documentación UX que el equipo sí usa (con ayuda de IA)

La documentación UX se ignora por dos motivos: no llega a tiempo o no ayuda a decidir/implementar. La solución no es escribir más, sino escribir mejor: docs cortos, orientados a decisiones, con criterios de aceptación, estados y riesgos. La IA funciona como acelerador para convertir hallazgos (research, análisis, sesiones) en artefactos accionables: tickets, specs, reglas de UI, edge cases y checklist de QA.

1) Qué hace que una doc de UX “se use” (y no se archive)

Una doc útil cumple estas 4 condiciones:

1. Está conectada a una decisión (qué se eligió y por qué).
2. Tiene un “owner” claro (quién la mantiene y cuándo caduca).
3. Es implementable (estados, edge cases, criterios de aceptación).
4. Está en el lugar del trabajo (Jira/Linear, PRD, Storybook, Notion/Confluence; no en un PDF olvidado).

La IA no arregla el sistema si el equipo sigue documentando “al final”. Pero sí puede reducir drásticamente el costo de producir docs que importan.

2) Plantilla: “UX Doc Accionable” (1–2 páginas, máximo)

Usa esta estructura como estándar. Si algo no cabe, probablemente no está priorizado.

1) Contexto (2–4 líneas)

• Problema del usuario / negocio
• Qué métrica quieres mover (1 primaria)
• Restricciones (tiempo, legal, plataforma)

2) Hallazgos (solo lo que cambia una decisión)

• 3–5 bullets con evidencia (cita breve o dato)
• Implicación directa (“por eso…”)

3) Decisión de diseño (la apuesta)

• Qué se hará (y qué no)
• Principio guía (1 frase): “Claridad > estética”, “Menos opciones > exploración”, etc.

4) Especificación de interacción (implementable)

• Flujo (pasos)
• Reglas (validación, permisos, límites)
• Estados (loading/empty/error/success)
• Accesibilidad mínima (labels, focus, contrast si aplica)
• Analítica (eventos a trackear)

5) Criterios de aceptación (Given / When / Then)

• 5–10 bullets claros; sin ambigüedad

6) Riesgos y mitigaciones (lo que puede salir mal)

• Riesgo UX (confusión, abandono)
• Riesgo técnico (latencia, dependencias)
• Riesgo legal (PII, consent)

7) QA checklist (rápido)

• Lo mínimo para release sin sorpresas

3) Cómo usar IA para convertir hallazgos en docs accionables

La IA es especialmente buena en 3 tareas:

A) Síntesis estructurada (de notas a decisiones)

Input: notas de entrevistas, insights, hallazgos sueltos
Output: “Hallazgos que cambian decisiones” + implicación + recomendación

Prompt recomendado:

• “Convierte estos hallazgos en 5 bullets accionables. Para cada uno: evidencia, implicación, y decisión sugerida. No inventes datos; si falta evidencia, marca ‘pendiente’.”

B) Generación de specs y edge cases (de Figma / flujo a implementación)

Input: descripción del flujo + pantallas + reglas de negocio
Output: estados, validaciones, errores, excepciones, accesibilidad

Prompt recomendado:

• “Actúa como UX Writer/Design Ops. A partir del flujo descrito, genera: reglas de interacción, estados, edge cases y mensajes de error. Prioriza claridad. No cambies el alcance.”

C) Criterios de aceptación y tickets (de doc a Jira/Linear)

Input: decisión y spec
Output: criterios Given/When/Then + subtareas (FE/BE/QA)

Prompt recomendado:

• “Convierte esta especificación en criterios de aceptación Given/When/Then. Luego sugiere subtareas para Frontend, Backend y QA. Sé específico y verificable.”

4) Ejemplos (antes → después)

Ejemplo 1: Insight de research → decisión

Antes (inútil):
“Los usuarios se confunden con el onboarding.”

Después (usable):
Hallazgo: 6/10 usuarios abandonan en el paso 2 porque no entienden por qué pedimos el dato X.
Implicación: incertidumbre = abandono temprano.
Decisión: mostrar “para qué lo usamos” + ofrecer “omitir por ahora”.
Métrica primaria: completion rate del onboarding.

Ejemplo 2: Diseño → especificación implementable

Antes (inútil):
“Agregar un modal de confirmación.”

Después (usable):
Regla: el modal aparece solo si el usuario editó campos y presiona “Salir”.
Estados:

• Loading: deshabilitar CTA, mostrar spinner
• Error: mensaje + reintento + conservar inputs
  Accesibilidad: focus trap dentro del modal; ESC cierra; labels en botones.
  Eventos: modal_view, modal_confirm_exit, modal_cancel_exit.

Ejemplo 3: “Se ve raro en mobile” → criterio verificable

Antes (inútil):
“Arreglar responsive.”

Después (usable):
AC:

• Given pantalla ≤ 390px, When cargo la página, Then el CTA permanece visible sin tapar contenido.
• Given teclado abierto, When el usuario escribe, Then el input activo se mantiene visible.

5) Do / Don’t (lo que separa docs ignoradas de docs usadas)

Do (sí)

• Escribe para implementación, no para “contar la historia”.
• Usa reglas verificables (“solo si…”, “si falla…”, “en este caso…”).
• Incluye estados y edge cases (donde nacen los bugs).
• Define métrica primaria + guardrail (evitas optimización accidental).
• Mantén la doc cerca del flujo (ticket/PRD), con dueño y fecha.

Don’t (no)

• No uses adjetivos sin métrica: “premium”, “moderno”, “limpio” (traduce a reglas).
• No documentes todo: documenta lo que reduce ambigüedad.
• No escondas la decisión: “se exploró…” sin “se eligió…”.
• No dependas de screenshots sin reglas: la UI cambia; las reglas permanecen.
• No uses IA para “inventar”: úsala para estructurar, no para suponer.

6) Checklist final (lista de “release-ready”)

1. ¿La doc responde “qué decidimos y por qué”?
2. ¿Hay 1 métrica primaria y 1–2 guardrails?
3. ¿El flujo tiene estados (loading/empty/error/success)?
4. ¿Existen criterios de aceptación verificables (Given/When/Then)?
5. ¿Quedaron enumerados edge cases (mínimo 5)?
6. ¿Incluye eventos de analítica (si aplica)?
7. ¿Hay checklist de QA y owner de validación?
8. ¿Está enlazada al ticket/épica y se puede encontrar en 10 segundos?
9. ¿Tiene owner y fecha de caducidad/revisión?
10. ¿La IA se usó para estructurar y acelerar, no para inventar?

Conclusión

La documentación UX que se usa no es la más larga: es la más operable. La IA te permite convertir hallazgos en decisiones, y decisiones en entregables verificables (AC, estados, edge cases). Cuando el equipo adopta una plantilla común, la documentación deja de ser “tarea extra” y se vuelve parte del delivery.

Si me compartes un ejemplo de tu doc actual (o un ticket real), te la reescribo con esta plantilla y te dejo los prompts listos para que tu equipo lo sistematice.