Cómo documentar tu app para que otra persona la tome

Para entregar una app a otra persona, documenta seis cosas: en qué cuentas y servicios corre, cómo levantarla en una computadora, cómo encajan sus partes, dónde viven los datos, cómo se despliega y se vuelve atrás, y qué se sabe que está roto. Un documento corto y correcto sobre eso vale más que uno largo que nadie actualiza, y le ahorra al siguiente desarrollador días de adivinar.

En esta guía verás qué escribir en cada parte, cómo reunir la información si no construiste la app tú, dónde guardarla y cómo comprobar que de verdad sirve.

¿Por qué vale la pena documentar?

Sin documentación, la persona siguiente tiene que redescubrirlo todo leyendo código y revisando paneles. Es lento y se le escapan cosas: una tarea programada que nadie mencionó, una variable de entorno que solo existe en producción, un webhook que apunta a una URL vieja. Cada sorpresa cuesta tiempo y a veces una caída.

La documentación también te protege a ti. Si un freelancer desaparece o termina la relación con una agencia, el conocimiento de cómo funciona tu app no debería irse con ellos.

¿Qué debe incluir el documento de entrega?

1. Cuentas y servicios

Una tabla con cada servicio del que depende la app:

Nunca pongas contraseñas ni claves en este documento. Escribe dónde están (por ejemplo, "en las variables de entorno del proyecto de hosting") y da acceso invitando a la persona nueva a cada servicio con su propia cuenta.

2. Cómo levantarla en local

Los pasos exactos para pasar de un clon recién descargado a una app funcionando en una laptop:

1. Herramientas y versiones necesarias (por ejemplo, la versión de Node.js).
2. Cómo instalar las dependencias.
3. Qué variables de entorno hacen falta, solo con el nombre, y un archivo de ejemplo como .env.example.
4. Cómo arrancar la app y qué URL abrir.
5. Cómo conseguir datos o una cuenta de prueba.

Pide a alguien que siga los pasos en una máquina limpia. Si se traba, falta un paso.

3. Cómo encajan las partes

Basta un resumen de una página, en palabras simples: con qué está hecho el frontend, qué hace el backend, qué APIs externas se llaman y para qué. Un diagrama ayuda, aunque sea la foto de uno dibujado en papel. Anota lo que sea poco habitual, como "los precios se calculan en una función de la base de datos, no en la app".

4. Los datos

• Dónde está la base de datos y cómo se respalda.
• Las tablas principales y qué representa cada una.
• Quién puede leer y escribir qué (por ejemplo, las políticas de Row Level Security en Supabase).
• Cómo se hacen los cambios de esquema: con archivos de migración o a mano en un panel. Si todavía es a mano, mira las migraciones con Supabase CLI.

5. El despliegue

• Cómo llega el código a producción: automático al fusionar o con un paso manual.
• Dónde está staging, si existe.
• Cómo volver atrás una versión mala.
• Tareas programadas, webhooks y procesos en segundo plano, con lo que los dispara.

6. Problemas conocidos y decisiones

Una lista corta y honesta: errores que conoces, soluciones temporales, funciones a medio terminar y decisiones que parecen raras pero fueron a propósito. Es la sección que más agradecen los desarrolladores nuevos, y la que más seguido falta.

¿Cómo juntas esto si no hiciste tú la app?

Si la app se hizo con un constructor de IA o con alguien que ya no está, igual puedes reunir casi todo:

1. Empieza por tus facturas. Cada servicio que pagas es uno que la app probablemente usa.
2. Mira las variables de entorno en el panel de tu hosting. Sus nombres (no los valores) te dicen con qué servicios habla la app.
3. Lee el archivo de paquetes (package.json en proyectos JavaScript). Ahí están las librerías que se usan.
4. Pregúntale a la herramienta de IA. En una herramienta que ve el código, prompts como "lista todos los servicios externos que llama este proyecto y desde dónde" o "escribe un README que explique cómo ejecutar este proyecto" dan un buen primer borrador. Compáralo con la realidad, porque puede equivocarse.
5. Revisa webhooks y tareas programadas en Stripe, Supabase y tu proveedor de hosting.

¿Dónde debe vivir la documentación?

Guárdala en el repositorio del código, como un README.md en la raíz y una carpeta docs/ para las páginas largas. Así queda junto al código, se versiona con él y cualquiera con acceso al código la encuentra. La guía de GitHub sobre archivos README explica lo básico.

¿Cómo la mantienes al día?

• Actualiza el documento en el mismo cambio que modifica la configuración: un servicio nuevo, una variable de entorno nueva o un paso de despliegue nuevo.
• Revísalo cada vez que entra alguien. Sus preguntas muestran lo que falta.
• Mantenlo corto. Los documentos largos son los primeros en quedar viejos.

Respuestas rápidas

¿Qué tan larga debe ser la documentación de entrega? Para una app pequeña, muchas veces bastan unas pocas páginas. Mejor correcta que larga.

¿Comparto contraseñas en la entrega? No. Invita a la persona nueva a cada servicio con su propio acceso y quita el acceso a quienes ya se fueron.

¿La herramienta de IA puede escribir la documentación por mí? Puede escribir un buen borrador a partir del código. Alguien tiene que verificarlo, sobre todo cuentas, datos y despliegue.

¿Qué es lo que más se olvida? Lo que está fuera del código: webhooks, tareas programadas, registros DNS y variables de entorno que solo existen en producción.

¿Vas a pasar la app a un equipo nuevo?

Si vas a cambiar de desarrollador, mira nuestra guía para entregar un proyecto de agente de IA a un desarrollador. También podemos hacernos cargo de una app y documentarla como parte de nuestro mantenimiento de software. Empieza con el chequeo gratuito de tu app o escríbenos.