Documentación que debes exigir al entregar un proyecto
Resumen:
- Seis documentos: accesos, arquitectura, despliegue, manual por rol, respaldos y pendientes.
- Se piden en el contrato, atados al último pago, no al final del proyecto.
- El inventario de accesos es el más importante: sin él no tienes control real.
- El código comentado no es documentación.
- Pedirla desde el inicio cuesta 5-10%; pedirla al final puede costar el doble.
La prueba que revela si tu sistema es tuyo
Hay una pregunta que resuelve la discusión: si mañana tu proveedor actual desapareciera, ¿otro equipo podría tomar el sistema y seguir trabajando sin empezar de cero?
En la mayoría de los proyectos de empresa mediana la respuesta es no. El sistema funciona, el código existe, y aun así nadie más puede tocarlo porque nadie sabe dónde está alojado, con qué cuentas, cómo se publica un cambio, qué servicios de terceros usa ni por qué se tomaron determinadas decisiones. Eso no es tener un sistema: es tener un sistema rentado a quien lo construyó.
La documentación es lo que cierra esa brecha, y son seis documentos. Ninguno largo.
Los seis
Uno: inventario de accesos y cuentas. Todos los servicios que el sistema usa, a nombre de quién está cada cuenta, quién tiene acceso, y dónde están las credenciales. Dominio, hosting, base de datos, correo transaccional, pasarela de pago, servicios de mensajería, repositorio de código. Y la verificación clave: cada cuenta a nombre de tu empresa, no del proveedor.
Dos: diagrama de arquitectura. Una página con las piezas y cómo se hablan. No necesita ser bonito; necesita que alguien técnico lo vea y entienda el panorama en cinco minutos.
Tres: instrucciones de despliegue reproducibles. Los pasos exactos para instalar el sistema desde cero y para publicar un cambio. La prueba de que sirven es que alguien que no construyó el sistema las siga y funcione.
Cuatro: manual de usuario por rol. No un manual de 200 páginas que nadie lee: una guía corta por rol, con las tareas que esa persona hace, idealmente con capturas.
Cinco: procedimiento de respaldo y restauración. Qué se respalda, cada cuánto, dónde se guarda, y los pasos para restaurar. Con la fecha de la última prueba de restauración real.
Seis: lista de pendientes conocidos y decisiones técnicas. Lo que quedó fuera del alcance, lo que se sabe que tiene limitaciones, y las decisiones importantes con su razón. Este es el documento que más agradece quien llega después, y el que más se omite.
| Documento | Extensión típica | Qué evita |
|---|---|---|
| Inventario de accesos | 1-2 páginas | Perder control del sistema |
| Arquitectura | 1 página | Semanas de exploración |
| Despliegue | 2-4 páginas | No poder publicar cambios |
| Manual por rol | 3-8 páginas por rol | Que el sistema no se use |
| Respaldo y restauración | 1-2 páginas | Pérdida de datos |
| Pendientes y decisiones | 2-5 páginas | Rehacer lo ya decidido |
Cómo asegurarte de que llegue
La mecánica importa más que la buena voluntad. Tres cosas funcionan.
Ponerla en el contrato como entregable nombrado, con la lista de los seis documentos, y atar el último pago a su recepción y aceptación. Un 10 o 15% final retenido hasta recibir documentación completa alinea incentivos como nada más.
Pedirla por partes, no al final. El inventario de accesos se puede pedir en la primera semana y actualizar; el diagrama, al cerrar el diseño. Escrito mientras se construye es preciso y casi gratis; reconstruido seis meses después es impreciso y caro.
Y hacer la prueba de recepción: que alguien que no sea el proveedor siga las instrucciones de despliegue en un ambiente limpio y las de restauración con un respaldo real. Si funcionan, la documentación sirve. Si no, no está terminada, y ese es el momento de decirlo.
Caso: un proveedor que desapareció
Una empresa de servicios turísticos en Quintana Roo tenía desde 2022 un sistema de reservas construido por un desarrollador independiente. Funcionaba bien. En 2025 el desarrollador dejó de responder: cambió de país y de actividad.
El sistema siguió operando porque nadie lo tocó. El problema llegó tres meses después, cuando la pasarela de pago cambió un requisito técnico y había que ajustar la integración. Nadie podía: el servidor estaba en una cuenta a nombre del desarrollador, el repositorio de código era privado y suyo, y el dominio estaba registrado con su correo.
Recuperar el control tomó once semanas. El dominio se recuperó por el proceso del registrador con documentación de la marca. Al servidor se entró porque el desarrollador había dejado una credencial compartida meses antes en un correo. El código se extrajo del servidor, sin historial. No había instrucciones de despliegue, así que reconstruir cómo se publicaba un cambio tomó dos semanas de prueba y error. El costo documentado de la recuperación fue de 310 mil pesos, más los pagos en línea caídos nueve días.
Al reconstruir contrataron el trabajo con los seis documentos nombrados en el contrato, 15% del pago retenido hasta recibirlos, y la prueba de despliegue en ambiente limpio como condición de aceptación. Costó un 8% más que la cotización original. El director lo resumió sin adornos: pagamos 310 mil por no haber pagado 60 mil.
¿Qué documentos debo exigir siempre?
Seis: inventario de accesos y cuentas, diagrama de arquitectura, instrucciones de despliegue reproducibles, manual de usuario por rol, procedimiento de respaldo y restauración, y lista de pendientes conocidos con decisiones técnicas tomadas.
¿Cuándo se pide la documentación?
En el contrato, como entregable ligado al último pago. Pedirla al final, cuando el proveedor ya cobró y está en otro proyecto, es la forma más confiable de no recibirla nunca o recibirla incompleta.
¿El código comentado cuenta como documentación?
No. Los comentarios en el código ayudan a quien ya está dentro, pero no responden las preguntas de quien llega: dónde vive esto, cómo se publica un cambio, qué cuentas existen, qué se decidió y por qué.
¿Cuál es el documento más importante?
El inventario de accesos. Sin él no tienes control real del sistema aunque tengas el código: no puedes entrar al servidor, al dominio, a la base ni a los servicios de terceros, y recuperar cada uno por separado toma semanas.
¿Cuánto encarece pedir documentación?
Entre un 5 y un 10% del proyecto si se pide desde el inicio, porque se escribe mientras se construye. Si se pide al final puede costar el doble, porque hay que reconstruir de memoria lo que se hizo meses antes.