[Informe de Clase] Introducción al Desarrollo de Sistemas — Semana 30: Institucionalizar las mejoras y la documentación
En la Semana 30 trabajamos en incorporar a las operaciones las mejoras de las Semanas 1–29 y en crear documentación (runbooks, registros de cambios, diseño de monitoreo) para que los resultados perduren. El tema fue evitar el “construir y olvidar” y, en cambio, empaquetar el trabajo para que el equipo y quienes se incorporen después puedan encargarse.
■ Introducción del profesor: “El conocimiento no vive solo en el código. Los procedimientos y los registros lo son todo.”
Sr. Tanaka: “Para que las mejoras no queden en acciones puntuales, es crucial escribir procedimientos, asignar responsables y construir un mecanismo para medir el impacto. Lo que hacemos hoy es un plano para el ‘tú del futuro’ y para ‘la próxima persona que se sume’.”
■ Objetivos de hoy
- Crear un Runbook (lista de verificación operativa) para integrar las mejoras en las operaciones.
- Establecer un formato y plantilla para el Changelog (registro de cambios).
- Decidir SLO/KPI para el monitoreo y esbozar un tablero sencillo.
- Redactar un playbook de primera respuesta para incidentes.
■ Ejercicio ①: Crear un Runbook (procedimiento operativo)
En equipos, los estudiantes tradujeron sus mejoras (p. ej., extender el TTL de caché, sanitización de entradas, ajuste de fallbacks) en procedimientos paso a paso que cualquiera pueda ejecutar. Secciones principales incluidas en el Runbook:
- Propósito (qué mejora se espera)
- Entornos objetivo (test / staging / producción)
- Prerrequisitos (variables de entorno requeridas, permisos, servicios dependientes)
- Pasos de ejecución (comandos y diffs de archivos)
- Pasos de reversión (cómo deshacer)
- Lista de verificación de verificación (qué KPI/logs confirmar)
- Campos para registrar ejecutor, aprobador y marca de tiempo de ejecución
Ejemplo breve de Runbook (extracto)
Propósito: Cambiar el TTL de caché de 300 → 900 para mejorar la respuesta en picos
Prerreq.: Acceso de escritura a config/cache_config.py
Pasos:
1. En staging, actualizar TTL = 300 a 900 en config/cache_config.py
2. Reiniciar el servicio: systemctl restart myapp
3. Ejecutar una prueba de carga de 10 minutos (script: load_test.py)
Verificación:
- El tiempo de respuesta promedio mejora respecto a la corrida anterior
- La tasa de errores (status != ok) no ha aumentado
Reversión:
- Volver el TTL a 300 y reiniciar el servicio
■ Ejercicio ②: Crear una plantilla de Changelog
Creamos una plantilla concisa para registrar cambios. Estos registros respaldan directamente análisis de causa raíz y evaluaciones posteriores.
Ejemplo de entrada de Changelog
- Fecha: 2025-10-01
- Autor: Yamada (Equipo A)
- Resumen: TTL de caché extendido de 300 → 900
- Propósito: Mejorar la respuesta en horas pico (reducir latencia promedio)
- Alcance del impacto: Respuestas de API (todos los usuarios)
- Entornos: staging → producción (despliegue gradual)
- Resultado: Latencia promedio −15% (prueba de carga), sin incidencias (revisión de ops)
- Referencia: runbooks/cache_ttl_update.md
■ Ejercicio ③: Diseño de monitoreo y boceto de tablero
Para observar continuamente las mejoras, elegimos métricas de monitoreo (KPI/SLO) y diseñamos un layout simple de tablero.
KPI recomendados (ejemplos)
- Tiempo de respuesta promedio (latencia media, ms)
- Tiempo de respuesta percentil 95 (p95, ms)
- Tasa de éxito (proporción con status == ok)
- Tasa de fallback (fallback / total)
- Tasa de solicitudes de regeneración (porcentaje de usuarios que presionaron “regenerar”)
Cada equipo también fijó umbrales y condiciones de alerta:
- Ejemplo: p95 > 2000 ms sostenido por 5 minutos → alerta en Slack
- Ejemplo: tasa de éxito < 95% → email al on-call
Para la clase, los tableros se compartieron como tablas simples más bocetos de series temporales.
■ Ejercicio ④: Playbook de primera respuesta ante incidentes (ligero)
Para acelerar la recuperación cuando ocurre un problema, redactamos un flujo de primera respuesta.
Flujo de primera respuesta (resumen)
- Detección (se recibe alerta de monitoreo)
- Evaluación del alcance (qué endpoints/usuarios están afectados)
- Mitigación inmediata (dividir tráfico / habilitar fallbacks)
- Recolección de datos de causa raíz (extraer logs de la ventana relevante)
- Escalamiento (notificar al responsable; si es necesario, informar vía el instructor a ops)
- Revisión post-recuperación (RCA) y entrada en el Changelog
■ La importancia de una cultura de documentación (discusión)
Cerramos con reglas operativas para la documentación.
- No te quedes en “escribir”: asigna un flujo de actualización y responsables.
- Registra siempre los cambios en el Changelog (automatiza cuando sea posible).
- Para runbooks, la prioridad es “¿puede el lector reproducirlo?” Usa viñetas y ejemplos de comandos.
- Estandariza nombres y estructura de archivos (p. ej.,
docs/runbooks/,docs/changelog.md).
Conclusión del alumnado: “¡Cuando imaginas quién lo leerá después, naturalmente escribes con más cuidado!”
■ Comentario de cierre del profesor
“Más allá de la tecnología, construir mecanismos para comunicar es el secreto de los resultados en equipo. Los runbooks y changelogs que hicieron hoy le facilitarán enormemente el trabajo a otra persona. Los pequeños hábitos se convierten en una gran confianza.”
■ Próxima semana: Cierre del trimestre y avance de temas de 2.º año
La próxima semana cerraremos el trimestre (entrega de hojas de reflexión y organización de portafolios) y presentaremos Diseño de Sistemas (UML, diseño de BD, arquitectura) para el próximo semestre. ¡Construyamos impulso para el aprendizaje de segundo año!
Tras la Semana 30, los estudiantes de primer año han adquirido la capacidad no solo de “construir” sino también de operar y comunicar. El mecanismo para institucionalizar pequeñas mejoras será un activo potente en el trabajo de desarrollo futuro. ¡Gran trabajo, equipo!