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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Redactar FAQ. Preguntas frecuentes que no encajan en las secciones anteriores. Formato pregunta-respuesta, directo y conciso.
- 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.