Cómo documentar tu software para no depender de una sola persona
La documentación de tu software tiene que permitir que una persona nueva ponga el sistema en marcha, lo despliegue y lo arregle sin llamar a quien lo construyó. Ese es el único criterio que importa. Si tu aplicación a medida, tu web o tu ERP solo los entiende una persona —un empleado, un freelance o el programador de confianza de siempre—, no tienes un sistema: tienes una dependencia. Y las dependencias se cobran solas el día que esa persona se va de vacaciones, cambia de trabajo o sube la tarifa. Documentar no es escribir un manual bonito de doscientas páginas que nadie abre; es dejar por escrito seis cosas concretas que en conjunto no suelen ocupar más de treinta folios.
Qué se rompe el día que falta quien lo construyó
El problema no aparece de golpe: aparece cuando hay que tocar algo. La aplicación funciona, los pedidos entran y nadie se preocupa. Hasta que llega una de estas situaciones y todo se para.
- Hay que cambiar un dato de configuración y nadie sabe en qué servidor vive la aplicación ni con qué usuario se entra.
- Se cae el sistema un lunes por la mañana y el único que sabía reiniciar el servicio no contesta al teléfono.
- Quieres pedir presupuesto a otro proveedor y, cuando pregunta qué tecnología usa, qué versión y cómo se despliega, no puedes responder.
- Entra un empleado nuevo en el equipo y tarda tres meses en ser útil, porque todo lo aprende preguntando.
- Pasas una auditoría o una certificación y te piden quién accede a qué datos: no hay documento que lo diga.
Lo caro de esto no es el incidente puntual, es el poder de negociación que pierdes. Un proveedor que es el único que entiende tu sistema no tiene ningún incentivo para documentarlo. Tú sí.
Los seis documentos que de verdad necesitas
No hace falta un departamento de documentación. Con estos seis documentos cubres el 90 % de las situaciones reales. Están ordenados por urgencia: si solo puedes hacer uno este mes, haz el primero.
1. El inventario de accesos y titularidades
Una lista con todo lo que compone tu sistema y a nombre de quién está: dominio y registrador, hosting o proveedor cloud, repositorio de código, cuentas de las tiendas de aplicaciones, pasarela de pago, servicios de correo, herramientas de terceros con sus licencias y fechas de renovación. Junto a cada entrada, dos datos: quién es el titular de la cuenta y quién tiene acceso hoy. Las contraseñas no van en este documento: van en un gestor de contraseñas de empresa, y el documento dice en qué gestor están.
2. El manual de despliegue
Los pasos exactos para pasar un cambio del ordenador del programador al sistema que usan tus clientes. Qué comandos se ejecutan, en qué orden, qué variables de entorno hacen falta, cómo se vuelve atrás si algo sale mal. Es el documento que más se agradece y el que casi nunca existe, porque la persona que despliega lo hace de memoria.
3. El mapa del sistema
Una página que explique, en palabras y con una lista, qué piezas tiene tu aplicación y cómo se hablan entre ellas: la web, la base de datos, el servicio que manda los correos, la integración con tu programa de facturación, el proceso que se lanza cada noche. No necesitas un diagrama técnico perfecto; necesitas que alguien entienda en diez minutos qué hay y de qué depende cada cosa.
4. El cuaderno de incidencias habituales
Los cinco o seis problemas que ya han pasado, con su síntoma y su solución: «si los correos no salen, revisa esto»; «si la sincronización de stock se queda parada, se reinicia así». Este documento se escribe solo, a base de ir anotando cada vez que se arregla algo. Es el que convierte una llamada de urgencia en una tarea de quince minutos.
5. Las decisiones y sus motivos
Por qué se eligió esa tecnología, por qué los pedidos se numeran de esa manera tan rara, por qué hay un campo que no se usa pero no se puede borrar. Sin esto, el siguiente equipo que entre dará por buena una decisión mala o romperá una decisión buena. Media página por decisión importante es suficiente.
6. El manual del usuario de negocio
Cómo se hacen las tareas del día a día en el sistema: dar de alta un cliente, cerrar un mes, sacar el listado que pide tu asesor. Lo escribe alguien de tu equipo, no el programador, y en el lenguaje de tu empresa. Es el que reduce las preguntas internas y el que te permite formar a alguien nuevo sin sentarte dos semanas a su lado.
Qué documento escribe quién y cada cuánto se revisa
| Documento | Para qué sirve | Quién lo escribe | Cuándo se revisa |
|---|---|---|---|
| Inventario de accesos y titularidades | Recuperar el control de todo lo que es tuyo | Tú o tu responsable interno | Cada vez que entra o sale alguien |
| Manual de despliegue | Poner cambios en marcha sin la persona de siempre | El proveedor o el programador | Con cada cambio de infraestructura |
| Mapa del sistema | Entender qué hay antes de tocar nada | El proveedor, revisado por ti | Una vez al año |
| Cuaderno de incidencias | Resolver lo repetido sin escalar | Quien resuelve cada incidencia | Continuo |
| Decisiones y motivos | No repetir errores ni romper lo que funciona | Quien toma la decisión | Cuando se decide algo relevante |
| Manual del usuario de negocio | Formar a gente nueva y reducir preguntas | Tu equipo | Con cada funcionalidad nueva |
Dónde guardarla para que alguien la encuentre
Una documentación que existe pero nadie localiza no sirve de nada. Tres reglas sencillas y sobran las discusiones.
- En una cuenta de tu empresa, no en la de una persona. Si el documento vive en el Drive personal de un empleado o en el ordenador del freelance, no es tuyo.
- Junto al código, siempre que sea documentación técnica. El manual de despliegue y el mapa del sistema deben estar en el mismo repositorio que la aplicación: así se actualizan en el mismo momento en que se cambia lo que describen.
- Un único sitio de entrada. Un documento índice que diga dónde está cada cosa. Si hay cuatro versiones del mismo manual en cuatro carpetas, nadie se fía de ninguna.
Cómo conseguir que tu proveedor la entregue y la mantenga
La documentación no se pide al final del proyecto, cuando ya no queda presupuesto ni ganas. Se pide en el contrato y se paga como parte de cada entrega.
- Escríbelo en el contrato. Que la documentación y el acceso al repositorio figuren entre los entregables, no como un favor. Si firmas un acuerdo de nivel de servicio, incluye ahí la obligación de mantener actualizado el manual de despliegue.
- Págala por entregas, no al final. Un porcentaje de cada hito se cobra cuando la documentación de ese hito está entregada y revisada.
- Pide que el titular de las cuentas seas tú. El proveedor trabaja con acceso delegado; la titularidad del dominio, del hosting y de las cuentas de las tiendas es de tu empresa.
- Revisa que se entienda. Si tú, sin ser técnico, no puedes seguir el índice y saber de qué va cada apartado, está escrita para el propio autor y no sirve de relevo.
La prueba del relevo: cómo saber si tu documentación sirve
Hay una forma de comprobarlo que no admite autoengaño. Coge a alguien que no haya trabajado nunca en el sistema —otro técnico de tu equipo, un proveedor externo, un informático de confianza— dale solo la documentación y pídele tres cosas: que levante el sistema en un entorno de pruebas, que haga un cambio pequeño y lo despliegue, y que resuelva una de las incidencias del cuaderno. Si lo consigue sin preguntar a quien lo construyó, estás cubierto. Si se atasca, ya sabes exactamente qué documento te falta: el que no pudo seguir.
Hazlo una vez al año y cuando cambie el equipo. Cuesta unas horas y es la única auditoría de documentación que mide algo real.
Por dónde empezar esta semana
Documentar tu software no es un proyecto de seis meses: es empezar por el inventario de accesos, que puedes tener listo en una tarde, y seguir por el manual de despliegue, que tienes que pedirle a quien despliega hoy. Con esos dos ya no te quedas bloqueado, aunque mañana falte quien construyó el sistema. El resto se escribe en pequeño, a medida que el sistema se toca. Si no sabes qué documentación tienes ni si la que tienes sirve, en Tangram Consulting podemos revisarla contigo, hacer la prueba del relevo sobre tu propio sistema y dejarte un índice de lo que falta: cuéntanos cómo está hoy tu aplicación y lo vemos sin compromiso.