user-guide

---
name: user-guide
description: "Usar para escribir guías de usuario o desarrollador. Activar ante: guia de usuario, como usar, manual de uso, tutorial, instrucciones para el usuario"
---

# Escribir guía de usuario

## Resumen

Este skill genera guías de usuario o de desarrollador claras y completas. Una buena guía permite al lector ir de "no sé nada de esto" a "lo tengo funcionando y entiendo cómo usarlo" sin necesidad de ayuda externa. El tono es directo, los pasos son verificables y los ejemplos son funcionales.

La guía se adapta al público: si es para usuarios finales, se evita jerga técnica; si es para desarrolladores, se incluyen detalles de configuración e integración.

## Proceso

1. **Identificar al público objetivo.** La guía se escribe de forma distinta según quién la va a leer:

   - **Usuario final:** pasos simples, capturas de pantalla si aplica, lenguaje no técnico.
   - **Desarrollador que integra:** ejemplos de código, documentación de API, configuración.
   - **Desarrollador que contribuye:** setup del entorno, convenios del proyecto, cómo ejecutar tests.

2. **Redactar la sección de instalación.** Paso a paso, sin saltar nada:

   - Requisitos previos (versiones de software, sistema operativo, herramientas necesarias).
   - Comandos de instalación exactos, copiables y pegables.
   - Verificación de que la instalación ha funcionado (comando o página de prueba).
   - Errores comunes de instalación y cómo resolverlos.

3. **Redactar la sección de configuración:**

   - Variables de entorno necesarias, con descripción y ejemplo de valor.
   - Ficheros de configuración, con plantilla y explicación de cada campo.
   - Valores por defecto y cuándo cambiarlos.

4. **Redactar la sección de uso básico.** El caso de uso más simple para que el lector vea resultados rápido:

   - Ejemplo mínimo funcional (de principio a fin).
   - Explicación de qué hace cada paso.
   - Resultado esperado para que el lector pueda verificar.

5. **Redactar la sección de uso avanzado.** Funcionalidades menos obvias pero importantes:

   - Configuraciones avanzadas.
   - Integraciones con otras herramientas.
   - Personalización y extensión.
   - Patrones de uso recomendados.

6. **Redactar la sección de troubleshooting.** Los problemas más comunes y sus soluciones:

   | Problema | Causa probable | Solución |
   |----------|---------------|----------|
   | Error X al arrancar | Falta variable de entorno Y | Añadir Y al fichero .env |
   | La página no carga | Puerto ocupado | Cambiar el puerto en config |

   Esta sección se alimenta de las preguntas reales de los usuarios. Si no hay histórico, anticipar los problemas más probables.

7. **Redactar FAQ.** Preguntas frecuentes que no encajan en las secciones anteriores. Formato pregunta-respuesta, directo y conciso.

8. **Revisar con un lector fresco.** Si es posible, pedir a alguien que no conoce el proyecto que siga la guía y reporte dónde se atasca.

## Criterios de éxito

- La guía cubre instalación, configuración, uso básico, uso avanzado y troubleshooting.
- Los pasos de instalación son reproducibles (se pueden seguir de cero a funcionando).
- Los ejemplos son funcionales y se pueden copiar directamente.
- El lenguaje está adaptado al público objetivo.
- Los problemas comunes tienen soluciones documentadas.