20. Documentación de instalación y configuración del sistema

20.1 Introducción

La documentación de instalación y configuración explica cómo preparar un sistema para que pueda ejecutarse correctamente. Es una de las documentaciones más prácticas del proyecto, porque permite que desarrolladores, operadores, administradores o usuarios técnicos puedan poner en marcha el software sin depender de explicaciones informales.

Una instalación puede fallar por muchos motivos: versiones incompatibles, dependencias faltantes, permisos incorrectos, variables de entorno mal definidas, servicios externos no disponibles o pasos ejecutados en orden incorrecto. Una buena guía reduce esos riesgos.

En este tema veremos cómo documentar requisitos previos, dependencias, entornos, instalación, configuración, verificación, problemas frecuentes y mantenimiento de la guía.

20.2 Qué es una guía de instalación

Una guía de instalación es un documento que indica los pasos necesarios para preparar y ejecutar un sistema en un ambiente determinado. Puede estar dirigida a desarrollo local, pruebas, producción, clientes internos o usuarios técnicos.

Su objetivo es que una persona de la audiencia prevista pueda repetir el proceso con resultados confiables. Por eso, debe ser secuencial, verificable y específica. No alcanza con decir "instalar dependencias"; hay que indicar cuáles, en qué versión y cómo comprobar que quedaron correctamente instaladas.

20.3 Elementos principales

La imagen muestra los elementos principales de una documentación de instalación y configuración: requisitos previos, dependencias, descarga del código, configuración, variables de entorno, base de datos, servicios externos, ejecución, verificación y solución de problemas.

20.4 Audiencia y ambiente

Antes de escribir una guía de instalación hay que definir para quién se escribe y en qué ambiente se aplicará. No es lo mismo instalar el sistema para desarrollo local que configurarlo en un servidor de producción.

Una guía para desarrolladores puede incluir herramientas de compilación, datos de prueba y comandos para ejecutar pruebas. Una guía para operación puede incluir permisos, servicios, variables seguras, monitoreo y verificación posterior. Una guía para clientes puede evitar detalles internos y concentrarse en requisitos y pasos soportados.

Si un proyecto tiene varios ambientes, conviene separar las instrucciones o indicar claramente qué pasos corresponden a cada uno.

20.5 Requisitos previos

Los requisitos previos indican qué debe existir antes de comenzar la instalación. Pueden incluir sistema operativo, versiones de lenguaje, motor de base de datos, herramientas, permisos, acceso a repositorios, certificados, credenciales o servicios externos.

Omitir requisitos previos es una causa común de bloqueo. El lector puede seguir pasos correctos y aun así fallar porque no tenía una versión compatible o un permiso necesario.

Conviene presentar los requisitos en una lista clara y, cuando sea posible, incluir comandos de verificación.

20.6 Dependencias

Las dependencias son componentes que el sistema necesita para funcionar: librerías, paquetes, servicios, bases de datos, colas, servidores web, herramientas de compilación o proveedores externos.

La documentación debe indicar cómo instalar dependencias, qué versiones son compatibles y qué hacer si una dependencia no está disponible. En proyectos modernos, parte de esta información puede estar en archivos como package.json, requirements.txt, pom.xml o docker-compose.yml, pero la guía debe explicar cómo usarlos.

20.7 Obtención del código o instalador

La guía debe indicar de dónde obtener el sistema: repositorio, paquete, instalador, imagen de contenedor, artefacto de compilación o enlace interno. También debe indicar versión, rama, etiqueta o canal de distribución cuando sea relevante.

Para desarrollo local, puede incluir el comando para clonar el repositorio. Para instalación en servidores, puede indicar qué artefacto descargar y cómo verificar su integridad.

20.8 Configuración

La configuración adapta el sistema a un ambiente. Puede incluir archivos de configuración, variables de entorno, conexiones a base de datos, rutas, credenciales, idioma, zona horaria, niveles de registro y características habilitadas.

La documentación debe explicar cada configuración importante: nombre, propósito, valor esperado, ejemplo, si es obligatoria y qué ocurre si falta. También debe indicar qué valores no deben publicarse por seguridad.

20.9 Variables de entorno

Las variables de entorno son frecuentes para configurar aplicaciones. Permiten separar código de configuración y evitar credenciales dentro del repositorio. Pero deben documentarse con cuidado.

Para cada variable conviene indicar nombre, descripción, ejemplo seguro, obligatoriedad, ambiente donde aplica y relación con otros valores. No se deben incluir secretos reales en la documentación.

20.10 Base de datos

Si el sistema usa base de datos, la guía debe indicar cómo crearla, configurar conexión, ejecutar migraciones, cargar datos iniciales y verificar que la aplicación puede conectarse.

En desarrollo local, puede incluir datos de prueba. En producción, debe indicar procedimientos seguros, respaldos previos y permisos necesarios. La instalación de la base de datos debe alinearse con la documentación de datos y migraciones.

20.11 Servicios externos

Muchos sistemas dependen de servicios externos: correo, pagos, autenticación, almacenamiento, mapas, colas, notificaciones o APIs de terceros. La guía debe indicar cómo configurar esas integraciones y cómo probar que funcionan.

También conviene documentar modos de prueba, entornos sandbox, credenciales necesarias, límites conocidos y comportamiento si el servicio externo no responde.

20.12 Ejecución del sistema

Una vez instaladas dependencias y configuración, la guía debe indicar cómo iniciar el sistema. Esto puede incluir comandos, servicios, contenedores, scripts o pasos manuales.

Además del comando de inicio, debe indicarse qué resultado esperar: puerto abierto, mensaje de inicio, URL de prueba, proceso activo o registro de confirmación. Sin esta verificación, el lector no sabe si terminó correctamente.

20.13 Verificación posterior

La verificación confirma que la instalación funciona. Puede incluir abrir una URL, ejecutar una prueba, consultar un endpoint de salud, revisar registros, comprobar conexión a base de datos o crear un registro de prueba.

Una guía sin verificación queda incompleta. El lector puede haber ejecutado todos los pasos, pero necesita una forma objetiva de saber si el sistema quedó listo.

20.14 Tabla de configuración

20.15 Problemas frecuentes

Una buena guía debe anticipar errores comunes. Puede incluir una sección de solución de problemas con síntomas, causas probables y acciones recomendadas.

Por ejemplo, si la aplicación no inicia, puede deberse a puerto ocupado, variable faltante, dependencia no instalada o error de conexión a base de datos. Documentar estas situaciones reduce consultas repetidas y acelera diagnósticos.

20.16 Seguridad en la configuración

La documentación de instalación debe cuidar la seguridad. No debe publicar contraseñas reales, tokens, claves privadas ni datos sensibles. Debe indicar cómo manejar secretos, permisos mínimos, archivos ignorados por control de versiones y configuración segura por ambiente.

También debe advertir si ciertos valores solo son válidos para desarrollo y no deben usarse en producción.

20.17 Errores frecuentes

Al documentar instalación y configuración suelen aparecer estos errores:

• No indicar versiones necesarias de herramientas y dependencias.
• Omitir permisos o accesos requeridos.
• No explicar variables de entorno.
• Incluir secretos reales en ejemplos.
• No indicar cómo verificar que la instalación funcionó.
• Mezclar instrucciones de desarrollo, pruebas y producción sin distinguir ambientes.
• No actualizar la guía cuando cambian dependencias o comandos.

20.18 Qué debes recordar de este tema

• La documentación de instalación debe permitir repetir el proceso desde cero.
• Debe definir audiencia y ambiente de aplicación.
• Los requisitos previos, dependencias y permisos deben estar explícitos.
• La configuración debe explicar variables, archivos, valores y consecuencias.
• No deben publicarse secretos reales en la documentación.
• Toda guía necesita verificación posterior y solución de problemas frecuentes.
• La guía debe mantenerse actualizada cuando cambian comandos, versiones o dependencias.

20.19 Conclusión

La documentación de instalación y configuración es esencial para que el sistema pueda ejecutarse de manera repetible y confiable. Una guía clara reduce bloqueos, errores de ambiente y dependencia de conocimiento informal.

En el próximo tema estudiaremos la documentación de despliegue: ambientes, versiones, dependencias y automatización.