¿Qué documentación debe entregarte tu proveedor de software?
Por el equipo de Stonework · Actualizada el · 6 min de lectura
Respuesta corta
Como mínimo, ocho documentos: instrucciones para instalar y correr el sistema, dos diagramas de arquitectura, los registros de decisiones, el diccionario de datos, un manual de usuario, un manual de operación, el inventario de cuentas y una bitácora de cambios. La prueba de que sirven la pone el manual de 18F: que un programador sin relación con el proyecto pueda levantar su propia copia del sistema siguiéndolos.
Los ocho documentos y para qué te sirve cada uno
| Documento | Qué contiene | Para qué te sirve |
|---|---|---|
| README | Qué es el sistema y cómo instalarlo, correrlo, probarlo y publicarlo | Que otro programador arranque sin llamar al anterior |
| Arquitectura | Dos diagramas: con qué se conecta tu sistema y de qué piezas está hecho | Saber qué pieza falla y qué cuesta cambiarla |
| Registros de decisiones | Una o dos páginas por cada decisión importante: contexto, decisión, estado y consecuencias | Saber por qué se hizo así antes de cambiarlo |
| Diagrama y diccionario de datos | Las tablas, cómo se relacionan, qué significa cada campo y cuáles guardan datos personales | Sacar reportes, migrar y saber qué datos personales tienes |
| Manual de usuario | Las tareas de cada rol, paso a paso | Capacitar a quien entra sin depender del proveedor |
| Manual de operación | Qué hacer si se cae, cómo restaurar un respaldo, cómo cambiar una llave, cómo dar de alta a alguien | Que una falla de noche no dependa de una sola persona |
| Inventario de cuentas | Cada servicio, a nombre de quién está, quién tiene acceso y dónde se guarda su llave | Saber qué es tuyo y qué pagas cada mes |
| Bitácora de cambios | Qué cambió en cada entrega, en lenguaje de negocio | Saber qué recibiste por lo que pagaste |
README es el nombre del archivo de instrucciones que va en la raíz del repositorio, la carpeta donde vive el código. Las contraseñas no van en ningún documento: van en un gestor de contraseñas que tú controlas, y el inventario solo dice dónde están.
La arquitectura: con dos diagramas basta
El modelo C4, de Simon Brown, describe un sistema en cuatro niveles: contexto, contenedores, componentes y código. Su propio sitio dice que no hace falta usar los cuatro, y que los diagramas de contexto y de contenedores bastan para la mayoría de los equipos.
Para una distribuidora, el de contexto muestra el sistema de pedidos al centro, a vendedores, almacén y clientes alrededor, y los servicios con los que habla: facturación, cobros, WhatsApp.
El de contenedores abre esa caja: la web, la app del repartidor y la base de datos, y cómo se comunican.
Con esos dos, un programador nuevo sabe qué está viendo antes de abrir el código. Los niveles de componentes y código cambian con cada entrega y se pueden leer en el propio código.
Registros de decisiones: el porqué de cada cosa
Michael Nygard propuso en 2011 un formato para registrar decisiones de arquitectura (ADR, por sus siglas en inglés). Su argumento: si nadie dejó escrito por qué se tomó una decisión, quien llega al proyecto solo tiene dos opciones, aceptarla a ciegas o cambiarla a ciegas.
Cada registro tiene título, contexto, decisión, estado y consecuencias, y mide una o dos páginas. Nygard los guarda en el mismo repositorio que el código, para que viajen juntos.
Un ejemplo de pyme: "Los pedidos descuentan inventario al facturar, no al cobrar. Contexto: los clientes pagan a crédito y el almacén surte antes. Consecuencia: el reporte de cobranza va aparte del de existencias."
Cómo ordenar la documentación: el marco Diátaxis
Diátaxis, de Daniele Procida, separa la documentación en cuatro tipos según lo que necesita quien la lee. Conviene no mezclarlos: un manual que intenta enseñar, explicar y servir de consulta a la vez es difícil de usar para cualquiera de las tres.
| Tipo | Lo que necesita el lector | Ejemplo en un sistema de pyme |
|---|---|---|
| Tutorial | Aprender, de la mano | "Tu primer día como cajero: abre caja, registra una venta y haz el corte" |
| Guía práctica | Resolver una tarea concreta | "Cómo cancelar una factura" o "Cómo dar de alta a un repartidor" |
| Referencia | Consultar datos exactos | La lista de roles y permisos, el diccionario de datos |
| Explicación | Entender por qué | Por qué el inventario se descuenta al facturar y no al cobrar |
El manual de usuario suele ser tutorial y guías prácticas. El diccionario de datos es referencia. Los registros de decisiones son explicación.
Lo que más se olvida: operación y bitácora
El manual de operación es el que se extraña a las once de la noche. En el libro de Google sobre operación de sistemas, Benjamin Treynor Sloss escribe que pensar y dejar por escrito de antemano qué hacer ante una falla mejora unas tres veces el tiempo promedio de reparación, frente a improvisar.
La bitácora de cambios no es el historial técnico del repositorio. Keep a Changelog la define como una lista curada y en orden cronológico de los cambios importantes de cada versión.
También advierte que copiar el historial técnico la llena de ruido. Para ti, cada entrega debería poder leerse en unos cuantos renglones.
Cómo comprobar que la documentación sirve
El manual de 18F, la oficina de tecnología del gobierno de Estados Unidos que cerró en 2025, pide que el software esté documentado de modo que un programador sin relación con el proyecto pueda usarlo para correr su propia copia. Esa es la prueba. Hazla antes del último pago:
- Pide a un programador que no haya trabajado en el proyecto que levante el sistema en su computadora solo con el README. Anota cada vez que tenga que preguntar algo.
- Pídele que restaure un respaldo en un ambiente de prueba siguiendo el manual de operación.
- Pide a alguien de tu equipo que haga una tarea que nunca ha hecho, solo con el manual de usuario.
- Entra a cada cuenta del inventario y revisa que esté a nombre de tu negocio.
- Elige algo del sistema que no entiendas y busca el registro de decisión que lo explica.
Cada pregunta que alguien tuvo que hacerle al proveedor es un hueco en la documentación. Pide que se corrija antes de cerrar. Las cuentas que deben estar a tu nombre están en ¿de quién es el código?.
Cuándo no necesitas tanto
Una página informativa o una herramienta que usa una sola persona no necesita registros de decisiones ni diagramas. Con el README, el inventario de cuentas y un manual de operación de una página, otra persona puede tomarla.
La lista completa tiene sentido cuando el sistema tiene varias piezas, varios roles y va a vivir años. Y si usas un programa de suscripción, la documentación es del fabricante; lo único tuyo que sigue haciendo falta es el inventario de cuentas.
Cómo pedirla
Si la documentación no está en el alcance escrito, nadie está obligado a entregarla.
Pide que la propuesta enliste cada documento, en qué formato se entrega y que forme parte de lo que se acepta en cada etapa. Las cláusulas están en qué debe decir un contrato de desarrollo.
Si ya tienes un proveedor que no documentó nada y no cumple en otras cosas, empieza por mi proveedor de software me está quedando mal.
Preguntas frecuentes
- ¿La documentación debe venir incluida en el precio?
- Debe aparecer en el alcance escrito. Si la propuesta no la menciona, asume que no está incluida y pídela antes de firmar.
- ¿En qué formato me la deben entregar?
- Lo técnico, en archivos de texto dentro del repositorio, para que viaje con el código. El manual de usuario, donde tu equipo lo consulte de verdad.
- ¿Quién la mantiene al día?
- Quien cambia el sistema. Pide que cada entrega actualice la bitácora y los documentos que toca, como parte de lo que se considera terminado.
- ¿Qué hago si mi proveedor no documentó nada?
- Pide primero el inventario de cuentas y el README: con eso otro programador puede empezar. Lo demás se puede reconstruir después leyendo el código.
Fuentes
- Diagramas del modelo C4. Simon Brown, c4model.com.
- Documentar decisiones de arquitectura. Michael Nygard, Cognitect, 15 de noviembre de 2011.
- Diátaxis: por dónde empezar. Daniele Procida.
- Manual de 18F para reducir el riesgo de proyectos de tecnología a la medida (Carnahan, Hart y Jaquith). 18F, entregado a la legislatura de Vermont, entregado el 17 de abril de 2025.
- Ingeniería de confiabilidad de sitios, capítulo 1: introducción (Benjamin Treynor Sloss). Google.
- Keep a Changelog, versión 1.1.0. Olivier Lacan.
Cómo hacemos estas guías. Cada cifra lleva su fuente y su fecha; lo que no tiene fuente no entra, y los ejemplos ilustrativos se dicen como tales. Las revisamos antes de publicarlas, cada tres meses y cuando cambia algo que citan.
Cuándo se revisa esta guía. Cuando cambien el modelo C4, el marco Diátaxis o el formato de Keep a Changelog.
Quién la escribe. El equipo de Stonework, un estudio de software en Ciudad de México que construye y opera EventQR, CuentaFácil y Conto, y hace software a la medida para negocios.