Saltar al contenido

Software a medida

Documentación de un software a medida: qué debe entregarte el proveedor y cuándo pedirla

Publicado el 6 min de lecturaLienzo Studio

La documentación de un software a medida es el conjunto de documentos que explican qué hace la herramienta, cómo se usa, cómo está construida y cómo se pone en marcha, junto con el código fuente y la lista de accesos a todo lo que necesita para funcionar. Debe entregarla el proveedor y mantenerla al día con cada versión. Es lo que permite que otra persona, otro equipo o el mismo proveedor dentro de unos años puedan mantener la herramienta sin empezar de cero ni depender de la memoria de nadie.

En pocas palabras: pide cuatro cosas. Un manual para quien usa la herramienta, una descripción de qué hace y con qué reglas, una documentación técnica para quien la mantenga y un inventario de accesos a nombre de tu empresa. Déjalo por escrito en el contrato, revísalo en cada entrega y compruébalo antes de que haga falta.

¿Para qué sirve la documentación de un software?

Mientras todo funciona y el mismo equipo se ocupa de la herramienta, la documentación parece un trámite. Su valor aparece cuando cambia algo:

  • Cambiar de proveedor sin quedarte atrapado. Si el equipo nuevo tiene que adivinar cómo está hecha la herramienta, el cambio se vuelve lento y caro. Lo contamos en cómo cambiar de proveedor de software.
  • Hacer el mantenimiento más ágil. Quien corrige un error o añade una función entiende antes qué tocar y qué puede romper.
  • Formar a las personas nuevas sin que alguien del equipo tenga que explicarlo todo de palabra.
  • Resolver dudas sobre por qué hace algo. Muchas reglas de negocio, como cuándo se aplica un descuento o quién aprueba un pedido, solo están en la cabeza de quien las pidió.
  • No depender de una sola persona, ni en tu empresa ni en la del proveedor.
  • Responder a clientes o auditorías que preguntan cómo se tratan los datos o qué controles hay.

¿Qué documentación debe entregar el proveedor?

No hace falta una montaña de papel, pero sí que cada pieza cubra a quien la va a necesitar:

DocumentoPara quiénQué incluye
Manual de usuarioQuien usa la herramientaCómo hacer cada tarea, paso a paso, con capturas
Documentación funcionalDirección y responsablesQué hace la herramienta, sus reglas de negocio, los roles y qué pasa en cada caso
Documentación técnicaQuien la mantengaCómo está organizada, cómo se instala, cómo se publica una versión y de qué servicios depende
Código fuenteQuien la mantengaTodo el código, con su historial de cambios, en un sitio al que tu empresa tenga acceso
Inventario de accesosLa empresaDominio, alojamiento, cuentas de servicios externos y quién es titular de cada una
Registro de cambiosTodosQué cambió en cada versión y cuándo
Copias y recuperaciónDirección y quien la mantengaDónde están las copias de seguridad y cómo se recupera la herramienta si algo falla

El manual de usuario

Explica cómo se hace cada tarea habitual, en el lenguaje de quien trabaja con la herramienta, no en el del equipo técnico. Funciona mejor organizado por tareas («cómo dar de alta un cliente», «cómo cerrar un parte») que por pantallas. Parte de él puede vivir dentro de la propia herramienta, con ayudas breves junto a cada campo.

La documentación funcional

Es la más olvidada y una de las más útiles. Recoge qué hace la herramienta y por qué: qué datos se guardan, qué reglas se aplican, qué puede hacer cada rol y qué ocurre en los casos especiales. Cuando dentro de un tiempo alguien pregunte por qué un pedido se bloquea en cierto estado, la respuesta tiene que estar aquí.

La documentación técnica

Está pensada para quien mantiene la herramienta. Debe explicar cómo está organizado el código, cómo se prepara un entorno para trabajar, cómo se publica una versión nueva, qué servicios externos usa y qué hacer ante los fallos más probables. Una buena prueba es que alguien que no la construyó consiga ponerla en marcha siguiendo solo esas instrucciones.

El inventario de accesos

Es una lista de todo aquello de lo que depende la herramienta: el dominio, el alojamiento, el servicio de envío de correos, las cuentas de los servicios conectados y cualquier otro acceso. Para cada uno, quién es el titular, quién tiene acceso y dónde se guardan las claves. Lo importante es que el titular sea tu empresa, no el proveedor ni una persona concreta.

¿Cuándo hay que pedir la documentación?

La documentación que se escribe al final suele llegar incompleta. Es mejor pedirla en cuatro momentos:

  1. En el presupuesto. Que conste qué documentación se incluye. Si dos presupuestos parecen iguales y uno no la menciona, no son iguales.
  2. En el contrato. Qué se entrega, en qué formato y quién es titular de cada cuenta y de cada documento. Lo explicamos en qué debe incluir un contrato de desarrollo de software.
  3. En cada entrega. Cada versión nueva debería llegar con el manual, la documentación técnica y el registro de cambios actualizados.
  4. Al terminar el mantenimiento o cambiar de proveedor. Una entrega completa y revisada, antes de cerrar la relación.

Si ya tienes una herramienta sin documentar, no es tarde: el mantenimiento de un software a medida es un buen momento para ir completándola por partes, empezando por el inventario de accesos.

¿De quién es la documentación y el código?

Depende de lo que diga el contrato. Lo habitual en un desarrollo a medida es que la empresa que lo encarga reciba el código y la documentación, pero no siempre está claro qué derechos se ceden y en qué condiciones. Repasamos las opciones en de quién es el código de un software a medida. Lo que se aplica en tu caso, confírmalo con tu asesor antes de firmar.

¿Cuánta documentación hace falta?

No se trata de volumen, sino de que sirva. Una herramienta pequeña puede quedar bien documentada en pocas páginas, y un documento enorme que nadie actualiza da una falsa sensación de seguridad. Tres criterios ayudan a decidir:

  • Que esté al día. Una documentación desactualizada confunde más que ayuda.
  • Que la encuentre quien la necesita, en un sitio conocido y con acceso de tu empresa.
  • Que responda a las preguntas reales: cómo se hace esto, por qué funciona así, cómo se arregla si falla.

Lo que no está documentado se convierte con el tiempo en una forma de deuda técnica: cada cambio cuesta más porque hay que redescubrir cómo estaba hecho.

¿Cómo comprobar que la documentación sirve?

La mejor forma es probarla antes de necesitarla:

  1. Pide a alguien que no participó en el proyecto que haga una tarea habitual siguiendo solo el manual.
  2. Repasa el inventario de accesos y comprueba que puedes entrar en cada servicio con una cuenta de tu empresa.
  3. Pregunta por una regla de negocio concreta y mira si la documentación funcional la explica.
  4. Pide al proveedor que muestre cómo se pondría en marcha la herramienta desde cero con lo que hay documentado.
  5. Anota lo que falte y fija cuándo se completa.

Errores habituales

  • Cuentas a nombre del proveedor o de una persona que ya no está en la empresa.
  • Dejar la documentación para el final, cuando ya no queda tiempo ni presupuesto para hacerla bien.
  • Tener solo el manual de usuario, sin la parte técnica.
  • Recibir el código sin instrucciones para ponerlo en marcha.
  • Guardar las contraseñas en un correo o en una hoja compartida con todo el mundo.
  • Reglas de negocio que solo conoce una persona.
  • No actualizar nada después de la primera versión.

En resumen

La documentación de un software a medida es lo que separa una herramienta que es tuya de una que depende de quien la hizo. Para que sirva:

  • Pide manual de usuario, documentación funcional, documentación técnica, código e inventario de accesos.
  • Déjalo por escrito en el presupuesto y en el contrato.
  • Exige que se actualice con cada entrega.
  • Comprueba que funciona antes de necesitarla.

Si tienes una herramienta sin documentar o vas a encargar una y quieres hacerlo bien desde el principio, puedes contarnos tu caso.

Preguntas frecuentes

¿Qué documentación debe entregar un proveedor de software a medida?

Como mínimo, un manual para quien usa la herramienta, una descripción de qué hace y con qué reglas, una documentación técnica que explique cómo está construida y cómo se pone en marcha, el código fuente con su historial y un inventario de todos los accesos y servicios de los que depende, a nombre de tu empresa. Conviene sumar un registro de los cambios de cada versión.

¿Cuándo hay que pedir la documentación de un software?

Desde el principio. Lo que incluye debe figurar en el presupuesto y en el contrato, y la documentación debe actualizarse con cada entrega, no escribirse al final. Si se deja para el último día, lo normal es que llegue incompleta o que no llegue, justo cuando más falta hace: al cambiar de proveedor o al terminar el mantenimiento.

¿Qué es la documentación técnica de un software?

Es la parte pensada para quien mantiene la herramienta, no para quien la usa. Explica cómo está organizado el código, cómo se instala, cómo se publica una versión nueva, de qué servicios externos depende y qué hacer si algo falla. Su objetivo es que otro equipo pueda hacerse cargo sin tener que adivinar cómo está hecho todo.

¿Es suficiente con tener el código fuente?

No. El código dice cómo está hecha la herramienta, pero no por qué se tomó cada decisión, ni cómo se pone en marcha, ni qué cuentas y servicios necesita para funcionar. Sin documentación técnica ni inventario de accesos, otro equipo puede tardar mucho en entenderlo, o no conseguir arrancarlo, aunque tenga el código completo.

¿Cómo sé si la documentación de mi software es buena?

Haz una prueba sencilla: pregúntate si otra empresa podría ponerla en marcha y mantenerla solo con lo que tienes. Pide a alguien que no haya participado que siga el manual para hacer una tarea habitual y comprueba que encuentras cada acceso en el inventario. Lo que falle en esa prueba es lo que hay que completar.

Ponorden.

Contacto · Primer paso

Cuéntanos qué te gustaría mejorar.Veamos qué podemos construir.

En una primera reunión vemos cómo trabaja tu empresa, qué necesitas y qué herramienta tendría sentido.

Hablemos

Sin compromiso. No necesitas saber de tecnología.

Reunión sin compromiso

Elige el día y la hora

Cargando la agenda…