La mayoría de los tickets de soporte de los productos de código fuente no son errores. Son problemas de instalación, dudas de configuración y peticiones del tipo "¿cómo cambio X?" que unas pocas páginas bien ubicadas habrían respondido. Una buena documentación de software para clientes se organiza en torno a esas preguntas: lo que el comprador necesita para instalar la aplicación, configurarla, usarla, personalizarla, actualizarla y arreglarla cuando algo sale mal.
La documentación también influye en que la gente compre o no. Es una de las señales de confianza que describimos en nuestra guía sobre cómo vender el código fuente de tu aplicación web o SaaS, y los revisores de AppTrovo comprueban que haya instrucciones claras de instalación y uso antes de publicar un producto. Esta guía te muestra qué escribir, en qué orden y cómo mantenerlo actualizado casi sin esfuerzo adicional.
El objetivo no es tener más páginas. Es tener menos tickets por venta, que es lo que hace que una licencia única sea rentable con el tiempo.
¿Qué documentos necesita un producto de código?
Los compradores de código fuente llegan con objetivos distintos en momentos distintos. Separa tu documentación por objetivo para que cada lector encuentre su respuesta rápidamente. El marco Diátaxis es un modelo muy conocido para esta división entre tutoriales, guías prácticas, referencia y explicación. Para una aplicación web que se vende, seis documentos lo cubren casi todo:
| Documento | Pregunta del lector | Evita tickets como |
|---|---|---|
| README / Inicio rápido | ¿Qué es esto y cómo lo pongo en marcha? | "¿Por dónde empiezo?", "¿Qué archivo subo?" |
| Guía de instalación | ¿Cómo lo instalo en mi servidor, paso a paso? | "Página en blanco después de subirlo", "Error de conexión a la base de datos" |
| Referencia de configuración | ¿Qué hace cada ajuste y cada variable de entorno? | "No se envían los correos", "¿Cómo cambio la moneda?" |
| Guía de usuario | ¿Cómo hago una tarea en la aplicación? | "¿Cómo añado a un empleado?", "¿Dónde están los informes?" |
| Guía de personalización | ¿Cómo modifico el código de forma segura? | "¿Cómo cambio el logotipo?", "¿Cómo añado un campo?" |
| Solución de problemas y notas de actualización | Algo se ha roto, o quiero la nueva versión | "Error 500 después de actualizar", "Los trabajos en cola no se ejecutan" |
Incluye la documentación dentro de la descarga (una carpeta docs/ o un archivo HTML) y publica el mismo contenido en línea. Los compradores que busquen un mensaje de error encontrarán una página pública; los compradores con un servidor sin acceso a internet podrán leer igualmente la copia local.
Empieza con un README escrito para compradores
Probablemente escribiste el README de tu repositorio para ti mismo. El README de un comprador responde a otras preguntas en la primera pantalla:
- Qué es, en una frase.
- Requisitos: versión del lenguaje, extensiones, base de datos, cron, cola y cualquier servicio de terceros de pago.
- Qué contiene el ZIP: qué carpeta hay que subir, cuál es la documentación y cuál es opcional (archivos de diseño, datos de ejemplo).
- El camino más rápido hasta tener la aplicación funcionando: de cinco a diez líneas, con un enlace a la guía de instalación completa.
- Los accesos predeterminados que crea el instalador, con un recordatorio para cambiarlos.
- Dónde obtener ayuda: enlace a la documentación, cómo abrir un ticket de soporte y qué incluir en él.
- Versión y enlace al registro de cambios.
Plantilla de guía de instalación
La guía de instalación evita más tickets que todo lo demás junto. Escríbela instalando tu producto en un servidor limpio mientras tomas notas, nunca de memoria. Usa esta estructura:
- Antes de empezar. Una lista de comprobación que el comprador pueda ir marcando: acceso al servidor, versión de PHP o del entorno de ejecución, extensiones necesarias, una base de datos y un usuario con todos los privilegios sobre ella, un dominio que apunte al servidor, certificado SSL y posibilidad de configurar una tarea cron.
- Sube los archivos. Indica exactamente qué carpeta va en cada sitio y cuál debe ser la raíz web (en una aplicación Laravel,
public/). Incluye una nota para hosting compartido por si no se puede cambiar la raíz web. - Instala las dependencias si no vienen incluidas, con los comandos exactos, como
composer install --no-dev --optimize-autoloader. - Crea el archivo de entorno. Copia
.env.examplea.envy enumera los valores que hay que cambiar. - Establece los permisos de archivos. Nombra los directorios que deben tener permisos de escritura, por ejemplo
storage/ybootstrap/cache/, y explica por qué en lugar de recomendar 777. - Ejecuta el instalador o las migraciones. Muestra lo que pide cada pantalla del instalador, incluido el paso de la clave de licencia.
- Configura las tareas programadas y las colas. Proporciona la línea de cron exacta y cómo ejecutar o supervisar los workers de la cola.
- Primer inicio de sesión y primeras tareas. Credenciales predeterminadas, los tres primeros ajustes que conviene cambiar y cómo enviar un correo de prueba.
- Verifica la instalación. Una lista breve de cosas que ya deberían funcionar, como "el panel se carga", "llega un correo de prueba", "la tarea programada aparece en el registro".
- Si algo ha salido mal: enlaces a los cinco errores de instalación más habituales en tu página de solución de problemas.
Añade una sección breve independiente para cada configuración de hosting habitual que admitas: un VPS con Nginx, un VPS con Apache, hosting compartido con cPanel, Docker. Si no admites alguna, dilo. Los compradores también pueden aprender el proceso general con guías como cómo instalar una aplicación web Laravel en un VPS, pero tu guía debe cubrir igualmente los pasos específicos de tu producto.
Escribe una referencia de configuración, no solo comentarios en .env
Los comentarios en .env.example ayudan a los desarrolladores, pero muchos compradores son propietarios de negocios o desarrolladores junior. Una tabla de referencia responde en un solo lugar a "¿qué hace esto y cuándo lo cambio?".
| Variable | Valor predeterminado | Qué hace | Cuándo cambiarla |
|---|---|---|---|
APP_URL | http://localhost | URL base usada en los enlaces y los correos | Siempre; ponle tu dominio real con https |
MAIL_MAILER | log | Cómo se envían los correos | Configúrala como smtp o con tu proveedor antes de pasar a producción |
QUEUE_CONNECTION | sync | Si los trabajos en segundo plano se ejecutan de inmediato o en un worker | Usa database o redis en sitios con mucho tráfico y ejecuta un worker |
APP_TIMEZONE | UTC | Zona horaria de las fechas y de las tareas programadas | Configúrala con la zona horaria de tu negocio |
La tabla anterior es un ejemplo; documenta todas las variables que lee tu producto. Haz lo mismo con las pantallas de ajustes dentro de la aplicación: qué cambia cada ajuste y cuál es el valor predeterminado seguro.
Solución de problemas: escribe entradas basadas en mensajes de error reales
Los compradores buscan el texto exacto que ven. Una página de solución de problemas que usa esos textos exactos como encabezados la encuentran tanto los buscadores como el propio buscador del sitio del comprador. Usa este formato para cada entrada:
Error:
SQLSTATE[HY000] [2002] Connection refusedQué significa: la aplicación no puede conectar con el servidor de base de datos.
Causas habituales:
DB_HOSToDB_PORTincorrectos; el servicio de base de datos no está en ejecución; el host solo acepta conexiones desde localhost.Cómo solucionarlo: revisa los valores de
.env, confirma que la base de datos está en ejecución, prueba127.0.0.1en lugar delocalhosty después borra la caché de configuración.
Empieza por los errores que ya conoces: una página en blanco con la depuración desactivada, el error 500 después de subir los archivos, errores de permisos en storage, la extensión de PHP que falta, fallos de autenticación del correo, cron que no se ejecuta y fallos en la verificación de la licencia. Después, añade una entrada nueva cada vez que un ticket revele un error nuevo.
Guía de personalización: responde a "¿cómo cambio X?"
Las peticiones de personalización son la segunda fuente de tickets más grande, y muchos vendedores las responden una por una para siempre. Documenta una sola vez los diez cambios más habituales:
- Cambiar el logotipo, los colores y el nombre de la aplicación.
- Editar las plantillas de correo y los textos de las notificaciones.
- Añadir o editar un idioma o una cadena de traducción.
- Añadir un campo a un formulario y a la base de datos.
- Añadir un elemento de menú o una página.
- Cambiar la moneda, el formato de fecha y el formato de número.
- Conectar otro proveedor de pagos, SMS o correo.
- Añadir un rol o un permiso.
Para cada uno, muestra dónde está el archivo, qué hay que cambiar y cómo conservar el cambio en futuras actualizaciones. Ese último punto es importante: si los compradores editan archivos del núcleo, cada actualización se convierte en un ticket de soporte. En lugar de eso, remítelos a puntos de extensión, carpetas de sobrescritura o la configuración. Nuestra guía sobre soporte, actualizaciones y control de versiones explica cómo diseñar las versiones para que las instalaciones personalizadas puedan actualizarse.
Convierte los tickets en documentación cada mes
La documentación se queda desactualizada y nunca lo cubre todo al primer intento. Un ciclo mensual sencillo la mantiene útil:
- Etiqueta cada ticket con una categoría: instalación, configuración, uso, personalización, error, preventa, otros.
- Una vez al mes, cuenta las etiquetas. Elige las tres preguntas más frecuentes que no sean errores.
- Escribe o mejora la página que habría respondido a cada una, usando en el encabezado las mismas palabras del comprador.
- Responde a los futuros tickets con un enlace y un resumen de una línea. Si el enlace no lo resuelve, hay que mejorar la página.
- Corrige el producto cuando la misma confusión se repita. Un mensaje de error más claro o una comprobación en el instalador es mejor que cualquier documento.
A modo de ejemplo ilustrativo, un vendedor que recibe 40 tickets al mes y descubre que 15 tratan sobre la configuración del correo normalmente puede eliminar la mayoría con una buena página y un paso del instalador que envíe un correo de prueba.
Haz que el producto se documente a sí mismo
La mejor documentación es la que el comprador nunca necesita abrir:
- Comprobaciones del instalador que verifiquen la versión de PHP, las extensiones, las carpetas con permisos de escritura y la conexión a la base de datos, y que expliquen los fallos en lenguaje sencillo.
- Mensajes de error útiles que digan qué hacer a continuación ("El servidor de correo rechazó el inicio de sesión. Revisa MAIL_USERNAME y MAIL_PASSWORD en Ajustes").
- Una página de estado del sistema en el área de administración que muestre las versiones, el estado de la cola, la última ejecución de cron y los permisos de almacenamiento. Los compradores pueden hacerle una captura de pantalla al abrir un ticket.
- Texto de ayuda contextual junto a los ajustes que se prestan a malentendidos.
- Estados vacíos que expliquen la siguiente acción ("Todavía no hay personal. Añade a tu primer empleado").
Reglas de estilo que hacen la documentación más fácil de seguir
- Escribe pasos numerados para todo lo que se hace en orden, con una acción por paso.
- Muestra los comandos y las rutas exactos, e indica dónde ejecutarlos.
- Indica el resultado esperado después de los pasos importantes, para que los lectores sepan cuándo algo ha ido mal.
- Usa capturas de pantalla para las pantallas de ajustes y actualízalas cuando cambie la interfaz.
- Escribe en un inglés estadounidense sencillo, con frases cortas; muchos compradores leen a través de una herramienta de traducción.
- Versiona la documentación. Marca las secciones que solo se aplican a determinadas versiones y conserva notas de actualización para cada versión publicada.
Los principios de documentación gratuitos de Write the Docs son una buena lista de comprobación para la claridad y la estructura.
Lista de comprobación de la documentación antes de enviar tu producto
- El README responde a qué es, requisitos, qué contiene el ZIP, inicio rápido, accesos predeterminados y dónde obtener ayuda.
- La guía de instalación se ha probado en un servidor limpio, con una sección para cada configuración de hosting admitida.
- La referencia de configuración cubre todas las variables de entorno y los ajustes importantes.
- La guía de usuario cubre las tareas principales de cada rol.
- La guía de personalización cubre los diez cambios más habituales y cómo conservarlos en las actualizaciones.
- La página de solución de problemas usa los mensajes de error exactos como encabezados.
- Se incluyen el registro de cambios y las notas de actualización.
- La documentación está en la descarga y en línea.
Antes de enviar tu producto, compáralo con la lista de comprobación para el envío de productos y con los estándares de código de AppTrovo. Cuando tu documentación esté lista, tu ficha puede enlazarla desde la sección de requisitos, lo que también ayuda a los compradores en la fase de preventa.
Preguntas frecuentes
¿Qué debe incluir la documentación de software orientada al cliente?
Como mínimo: un README, una guía de instalación, una referencia de configuración, una guía de usuario, una guía de personalización y una página de solución de problemas con notas de actualización. Cada documento responde a una pregunta distinta, así que mantenlos separados y enlázalos entre sí.
¿La documentación debe ir dentro del ZIP o en línea?
En ambos sitios. La copia del ZIP siempre coincide con la versión que tiene el comprador. La copia en línea se puede buscar, es fácil de enlazar desde las respuestas de soporte y se puede actualizar entre versiones. Deja claro a qué versión se aplica cada página en línea.
¿Qué nivel de detalle debe tener una guía de instalación?
El suficiente para que alguien que ya ha instalado alguna aplicación web, pero nunca la tuya, pueda terminar sin ponerse en contacto contigo. Incluye los comandos exactos, las rutas, los permisos necesarios y el resultado esperado después de cada paso importante. Pruébala en un servidor limpio en cada versión que cambie los requisitos.
¿Cómo sé qué documentación escribir primero?
Revisa tus tickets de soporte y las preguntas de preventa. La instalación y la configuración suelen ir primero, seguidas de las peticiones de personalización más habituales. Si todavía no tienes tickets, instala tú mismo el producto en un servidor limpio y documenta cada punto en el que hayas tenido que pararte a pensar.
¿De verdad una buena documentación reduce los reembolsos?
Las instalaciones fallidas y las expectativas no cumplidas son motivos habituales por los que los compradores piden reembolsos, y unos requisitos claros junto con una guía de instalación probada resuelven ambos. Los reembolsos en AppTrovo se rigen por la política de reembolsos, pero prevenir el problema siempre es más barato que gestionar la solicitud.