La documentación técnica de software que debe entregarte tu proveedor cubre como mínimo siete piezas: arquitectura, contrato de la API, modelo de datos, despliegue, runbook de operación, decisiones de arquitectura y manual de usuario. Con ese paquete otro equipo puede mantener la aplicación sin depender de quien la escribió. Es lo que conviene exigir a cualquier equipo, también al del desarrollo de software a medida de Codezone en Madrid.
Sin documentación, cada cambio empieza con días de arqueología en el código y la dependencia del proveedor original se convierte en un riesgo de negocio. Es el punto de partida típico al rescatar un proyecto de software abandonado por otro proveedor: el código existe, pero nadie sabe cómo se despliega ni por qué se diseñó así.
Al terminar tendrás una lista para tu contrato y tu acta de aceptación, complementaria a la revisión de calidad del código antes de heredar un software.
Qué es la documentación técnica de software
La documentación técnica de software es el conjunto de documentos que describe cómo está construida y cómo se opera una aplicación, incluidas las decisiones que llevaron a ese diseño. Va dirigida a desarrolladores y responsables técnicos; el manual de usuario, en cambio, explica el uso diario a quien trabaja con la aplicación.
Los Siete Documentos Mínimos que Debe Entregarte el Proveedor
Un proveedor profesional entrega siete piezas de documentación, y cada una responde a una pregunta distinta del equipo que venga después.
- Arquitectura: diagramas según el modelo C4 para visualizar arquitectura de software, que propone cuatro niveles de zoom desde el contexto del sistema hasta el código. La plantilla arc42 sirve de índice si necesitas más detalle.
- Contrato de API: especificación en formato OpenAPI, en YAML o JSON, versionada en el repositorio. La OpenAPI Specification oficial define una descripción estándar de APIs HTTP independiente del lenguaje. Cómo evolucionarla sin romper clientes lo vimos en versionado de APIs en producción.
- Modelo de datos: diagrama de entidades con el historial de migraciones del esquema.
- Despliegue e infraestructura: variables de configuración sin valores secretos y pasos para levantar cada entorno desde cero, mejor como código si usas contenedores Docker para empaquetar la aplicación.
- Runbook de operación: qué hacer cuando algo falla, desde un reinicio hasta restaurar una copia, y a quién avisar. Encaja con la arquitectura del mantenimiento de una web en producción.
- Decisiones de arquitectura (ADR): un registro breve por decisión con el contexto, las alternativas descartadas, la opción elegida y sus consecuencias.
- Manual de usuario: guía por perfil para quien usa la aplicación cada día.
Dónde Vive la Documentación y Quién la Actualiza
La documentación útil vive en el mismo repositorio que el código y cambia en el mismo commit. Un wiki separado se desactualiza en cuanto el equipo tiene prisa.
La regla práctica es sencilla: todo pull request que modifica una API o el esquema de datos actualiza su documento en el mismo cambio, y la revisión lo comprueba. Así la documentación técnica del proyecto refleja lo que de verdad hay en producción.
Cómo Exigir la Documentación en el Contrato y la Aceptación
La documentación se exige con dos cláusulas: una que la lista como entregable de cada hito y otra que condiciona la aceptación del hito a que exista y esté al día.
- Contrato: anexo con la lista de documentos y su ubicación en el repositorio, más la cesión de derechos sobre ellos junto al código. Lo desarrollamos en quién es dueño del código que pagas.
- Aceptación: el acta de cada hito verifica que un tercero puede desplegar siguiendo solo el documento de despliegue.
- Pago: el último pago queda ligado a la entrega del paquete completo.
- Sprints: si trabajas en iteraciones, la documentación entra en la definición de hecho, como explicamos en metodología ágil con un proveedor de software externo.
CodeZone Pro Tip: este script comprueba que un repositorio contiene los documentos mínimos pactados, que hay al menos una ADR y que la especificación declara OpenAPI 3.x.
import re
import sys
from pathlib import Path
# Rutas acordadas en el anexo del contrato; ajústalas a tu convención
MINIMOS = {
"Arquitectura": ["docs/arquitectura.md"],
"Contrato de API": ["docs/openapi.yaml", "docs/openapi.json"],
"Modelo de datos": ["docs/modelo-datos.md"],
"Despliegue": ["docs/despliegue.md"],
"Runbook": ["docs/runbook.md"],
"Manual de usuario": ["docs/manual-usuario.md"],
}
def comprobar(repo: Path) -> int:
faltan = [n for n, rutas in MINIMOS.items()
if not any((repo / r).is_file() for r in rutas)]
# Una ADR por decisión, numerada: 0001-elegir-base-de-datos.md
adrs = sorted((repo / "docs" / "adr").glob("[0-9][0-9][0-9][0-9]-*.md"))
if not adrs:
faltan.append("Decisiones de arquitectura (ADR)")
spec = next((repo / r for r in MINIMOS["Contrato de API"]
if (repo / r).is_file()), None)
# El campo openapi fija la versión de la especificación; exigimos la rama 3.x
if spec and not re.search(r'"?openapi"?\s*:\s*["\']?3\.', spec.read_text("utf-8")):
faltan.append(f"{spec.name} no declara openapi 3.x")
for f in faltan:
print(f"[FALTA] {f}")
print(f"ADR encontradas: {len(adrs)}")
return 1 if faltan else 0
if __name__ == "__main__":
sys.exit(comprobar(Path(sys.argv[1] if len(sys.argv) > 1 else ".")))Ejecutado en la integración continua, este control bloquea la entrega de un hito si falta un documento. La cláusula del contrato deja de depender de que alguien lo revise a mano y la aceptación se basa en un resultado objetivo.
Lo que Pierdes al Aceptar un Software sin Documentar
Aceptar un software sin documentación traslada el coste al futuro: cada cambio y cada relevo de proveedor empiezan por reconstruir lo que nadie escribió. Exigirla en el contrato cuesta una página de anexo.
Si tu aplicación ya está en producción sin estos documentos, se pueden reconstruir a partir del código y del entorno actual. Es un trabajo que encaja dentro de un contrato de soporte técnico y mantenimiento de Codezone.
Si quieres saber qué le falta a la documentación de tu aplicación, pídenos una revisión de tu documentación técnica.
