686f6c61/user-guide

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.