Tema 32. Construcción del sistema. Entornos de construcción y generación de código. Despliegue de aplicaciones e integración continua. Dev-Ops. Estándares de documentación. Manuales de usuario y manuales técnicos. Formación de usuarios y personal técnico: métodos y materiales.

1. Construcción del sistema

1. Construcción del sistema

🎯 Idea clave

• La construcción del sistema es la fase del ciclo de vida donde se transforma el diseño en código ejecutable y funcional.
• Requiere el uso de entornos controlados que garanticen la calidad y trazabilidad del software desarrollado.
• Incluye procesos de generación de código, pruebas unitarias y preparación para el despliegue.
• Debe alinearse con los estándares de documentación y normativa aplicable en la Administración General del Estado.
• La integración continua y las prácticas DevOps son elementos clave para optimizar esta fase.
• La formación del personal técnico y de usuarios es un componente esencial para asegurar el éxito del sistema.

📚 Desarrollo

Definición y alcance. La construcción del sistema abarca todas las actividades necesarias para convertir el diseño técnico en un producto software operativo. Este proceso incluye la codificación, las pruebas unitarias, la integración de componentes y la preparación para el despliegue en entornos de producción. En el ámbito de la Administración General del Estado, esta fase debe ajustarse a los marcos normativos establecidos, como el Real Decreto 405/2023 y las normas ISO/IEC 12207 e ISO/IEC 25000.

Entornos de construcción. Los entornos utilizados en esta fase deben ser estables, reproducibles y estar aislados de otros sistemas para evitar interferencias. Estos entornos permiten la generación de código de manera automatizada, facilitando la detección temprana de errores y la validación de funcionalidades. La configuración de estos entornos debe documentarse de forma exhaustiva para garantizar su replicabilidad y mantenimiento.

Generación de código. La generación de código puede realizarse de forma manual o automatizada, dependiendo de la complejidad del sistema y las herramientas disponibles. En la Administración General del Estado, se prioriza el uso de estándares que aseguren la interoperabilidad y la reutilización de componentes. Además, se fomenta la aplicación de buenas prácticas de programación, como la modularidad y la claridad en el código fuente.

Pruebas unitarias. Las pruebas unitarias son un componente crítico de la construcción del sistema, ya que permiten validar el funcionamiento de cada módulo de manera individual. Estas pruebas deben diseñarse para cubrir todos los casos de uso definidos en la especificación de requisitos, asegurando que el código cumple con las funcionalidades esperadas. La automatización de estas pruebas es una práctica recomendada para agilizar el proceso y reducir errores humanos.

Integración continua. La integración continua es una metodología que consiste en fusionar el código desarrollado por diferentes equipos de manera frecuente y automatizada. Este enfoque permite detectar y resolver conflictos de integración de forma temprana, mejorando la calidad del software y reduciendo los tiempos de entrega. En la Administración General del Estado, la integración continua se alinea con las prácticas DevOps para optimizar el ciclo de vida del desarrollo.

Documentación técnica. La documentación generada durante la construcción del sistema debe cumplir con los estándares establecidos, como el IEEE 1063. Esta documentación incluye manuales técnicos, guías de instalación y configuración, y registros de las pruebas realizadas. La claridad y precisión en la documentación son esenciales para facilitar el mantenimiento futuro y la formación del personal técnico y de usuarios.

Formación y capacitación. La formación del personal técnico y de los usuarios finales es un aspecto fundamental para garantizar el correcto funcionamiento del sistema. Los métodos de formación pueden incluir sesiones presenciales, materiales didácticos en línea y manuales de usuario. La capacitación debe adaptarse a las necesidades específicas de cada grupo, asegurando que todos los actores involucrados comprendan el sistema y puedan utilizarlo de manera eficiente.

🧩 Elementos esenciales

• Ciclo de vida: Proceso estructurado que abarca desde el diseño hasta el despliegue del sistema, asegurando su calidad y funcionalidad.
• Entornos de construcción: Infraestructuras controladas y aisladas donde se desarrolla y prueba el código, garantizando estabilidad y reproducibilidad.
• Generación de código: Proceso de creación de software, ya sea manual o automatizado, siguiendo estándares de calidad y buenas prácticas.
• Pruebas unitarias: Validación individual de cada módulo del sistema para asegurar que cumple con los requisitos funcionales.
• Integración continua: Metodología que permite fusionar el código de manera frecuente y automatizada, detectando errores de integración tempranamente.
• DevOps: Conjunto de prácticas que integran el desarrollo y las operaciones para optimizar el ciclo de vida del software.
• Documentación técnica: Registros detallados que describen el funcionamiento, configuración y mantenimiento del sistema, siguiendo estándares como el IEEE 1063.
• Manuales de usuario: Guías diseñadas para facilitar el uso del sistema a los usuarios finales, adaptadas a su nivel de conocimiento.
• Formación del personal: Actividades y materiales destinados a capacitar a técnicos y usuarios en el manejo y mantenimiento del sistema.
• Normativa aplicable: Marco legal y técnico que regula la construcción del sistema, como el Real Decreto 405/2023 y las normas ISO/IEC 12207 y 25000.
• Trazabilidad: Capacidad de rastrear cada componente del sistema desde su diseño hasta su implementación, asegurando la coherencia y calidad.
• Automatización: Uso de herramientas para agilizar procesos como pruebas, integración y despliegue, reduciendo errores humanos.

🧠 Recuerda

• La construcción del sistema es una fase crítica que transforma el diseño en un producto funcional y operativo.
• Los entornos de construcción deben ser estables, reproducibles y estar bien documentados.
• Las pruebas unitarias son esenciales para validar el funcionamiento de cada módulo del sistema.
• La integración continua permite detectar y resolver conflictos de manera temprana, mejorando la calidad del software.
• La documentación técnica debe cumplir con estándares como el IEEE 1063 para garantizar su utilidad y claridad.
• La formación del personal técnico y de usuarios es clave para el éxito del sistema.
• La normativa aplicable, como el Real Decreto 405/2023, debe guiar todas las actividades de construcción.
• La automatización de procesos reduce errores y optimiza los tiempos de entrega.
• La trazabilidad asegura que cada componente del sistema pueda rastrearse desde su diseño hasta su implementación.
• Las prácticas DevOps integran el desarrollo y las operaciones para mejorar la eficiencia del ciclo de vida del software.

2. Entornos de construcción y generación de código

2. Entornos de construcción y generación de código

🎯 Idea clave

• Los entornos de construcción son infraestructuras aisladas donde se compila, empaqueta y verifica el código fuente antes de su despliegue.
• La generación de código automatiza la creación de componentes repetitivos, reduciendo errores y acelerando el desarrollo.
• Estos entornos deben replicar fielmente las condiciones de producción para garantizar la consistencia del software.
• La integración con herramientas de control de versiones es esencial para gestionar cambios y versiones de manera eficiente.
• La estandarización de entornos evita problemas de compatibilidad entre diferentes fases del ciclo de vida del sistema.
• La automatización en estos entornos facilita la detección temprana de fallos y mejora la calidad del software.

📚 Desarrollo

Definición y propósito. Los entornos de construcción son espacios controlados donde se ejecutan procesos de compilación, empaquetado y pruebas automatizadas. Su objetivo principal es asegurar que el código fuente se transforme en un producto ejecutable sin dependencias no resueltas o errores de configuración. Estos entornos actúan como una capa intermedia entre el desarrollo y la producción, permitiendo validar el software en condiciones similares a las reales.

Componentes clave. Un entorno de construcción típico incluye herramientas de compilación, gestores de dependencias, sistemas de control de versiones y frameworks de pruebas. Estas herramientas trabajan de manera coordinada para automatizar tareas repetitivas, como la generación de artefactos o la ejecución de tests unitarios. La configuración de estos componentes debe ser reproducible, evitando diferencias entre entornos que puedan introducir errores.

Generación de código. La generación automática de código se utiliza para crear componentes estandarizados, como interfaces de usuario, modelos de datos o servicios web. Esta técnica reduce la carga de trabajo manual y minimiza errores humanos en tareas repetitivas. Herramientas como generadores de plantillas o frameworks de desarrollo suelen integrarse en estos entornos para agilizar la producción de código base.

Integración con control de versiones. Los entornos de construcción deben estar sincronizados con sistemas de control de versiones, como Git o Subversion. Esto permite gestionar cambios en el código de manera centralizada y facilita la trazabilidad de las modificaciones. La automatización de procesos, como la compilación tras cada commit, asegura que el software se valide de forma continua, detectando problemas en etapas tempranas.

Reproducibilidad. Uno de los principios fundamentales de estos entornos es la reproducibilidad. Esto significa que cualquier construcción del software debe generar el mismo resultado independientemente del momento o la máquina en la que se ejecute. Para lograrlo, se utilizan herramientas de gestión de configuración y contenedores, que encapsulan las dependencias y evitan conflictos entre versiones de librerías o sistemas operativos.

Automatización de pruebas. Los entornos de construcción incorporan frameworks de pruebas automatizadas, como JUnit o Selenium, para validar el funcionamiento del software. Estas pruebas se ejecutan de manera sistemática durante el proceso de construcción, garantizando que el código cumple con los requisitos funcionales y no funcionales antes de su despliegue. La automatización de pruebas reduce el tiempo de detección de errores y mejora la calidad del producto final.

Escalabilidad y flexibilidad. Estos entornos deben ser escalables para adaptarse a proyectos de diferentes tamaños y complejidades. La utilización de infraestructuras en la nube o sistemas de integración continua permite ajustar los recursos según las necesidades del proyecto. Además, la flexibilidad en la configuración facilita la adaptación a diferentes tecnologías o lenguajes de programación, sin comprometer la estabilidad del proceso.

Seguridad y cumplimiento. En el ámbito de la Administración General del Estado, los entornos de construcción deben cumplir con normativas de seguridad, como el Esquema Nacional de Seguridad (ENS). Esto implica la implementación de controles de acceso, la gestión segura de credenciales y la auditoría de los procesos de construcción. La seguridad en estos entornos es crítica para evitar vulnerabilidades en el software desplegado.

🧩 Elementos esenciales

• Entorno de construcción: Infraestructura aislada donde se compila y empaqueta el código fuente, garantizando condiciones reproducibles.
• Generación automática de código: Técnica para crear componentes estandarizados, reduciendo errores y acelerando el desarrollo.
• Herramientas de compilación: Software como Maven, Gradle o Make, que transforman el código fuente en artefactos ejecutables.
• Gestores de dependencias: Sistemas como npm o pip, que resuelven y gestionan las librerías externas necesarias para el proyecto.
• Control de versiones: Integración con sistemas como Git para gestionar cambios y mantener la trazabilidad del código.
• Pruebas automatizadas: Frameworks como JUnit o Selenium, que validan el software durante el proceso de construcción.
• Contenedores: Tecnologías como Docker, que encapsulan las dependencias y garantizan la reproducibilidad del entorno.
• Integración continua: Práctica que automatiza la construcción y pruebas tras cada cambio en el código.
• Configuración reproducible: Uso de herramientas como Ansible o Terraform para definir entornos de manera declarativa.
• Seguridad en entornos: Implementación de controles de acceso y auditorías para cumplir con normativas como el ENS.
• Artefactos: Productos generados durante la construcción, como archivos ejecutables o paquetes instalables.
• Escalabilidad: Capacidad del entorno para adaptarse a proyectos de diferentes tamaños y complejidades.

🧠 Recuerda

• Los entornos de construcción son esenciales para garantizar la calidad y consistencia del software.
• La automatización reduce errores humanos y acelera el desarrollo.
• La reproducibilidad evita problemas de compatibilidad entre entornos.
• La integración con control de versiones facilita la gestión de cambios.
• Las pruebas automatizadas son clave para detectar fallos en etapas tempranas.
• La seguridad en estos entornos es crítica en el ámbito de la Administración Pública.
• La generación de código estandariza componentes y reduce la carga de trabajo manual.
• La escalabilidad permite adaptar el entorno a las necesidades del proyecto.
• La configuración declarativa asegura que los entornos sean consistentes y reproducibles.
• El cumplimiento normativo, como el ENS, debe integrarse en estos entornos.

3. Despliegue de aplicaciones e integración continua

3. Despliegue de aplicaciones e integración continua

🎯 Idea clave

• El despliegue de aplicaciones consiste en trasladar el software desarrollado a entornos operativos donde los usuarios finales puedan utilizarlo.
• La integración continua es una práctica que automatiza la construcción, prueba y validación del código cada vez que se realiza un cambio.
• Ambos procesos buscan reducir errores humanos y acelerar la entrega de versiones estables del sistema.
• El despliegue automatizado garantiza que las actualizaciones se implementen de forma coherente en todos los entornos.
• La integración continua facilita la detección temprana de fallos mediante pruebas automatizadas.
• Estos procesos son fundamentales en entornos DevOps para lograr ciclos de desarrollo ágiles y fiables.

📚 Desarrollo

Definición y objetivos. El despliegue de aplicaciones es el proceso mediante el cual el software desarrollado se instala y configura en los entornos de producción, preproducción o pruebas. Su objetivo principal es garantizar que los usuarios finales accedan a una versión funcional y estable del sistema, minimizando interrupciones y errores durante la transición. Este proceso incluye la transferencia de archivos, la configuración de bases de datos, la actualización de servicios y la verificación de que todos los componentes interactúan correctamente.

Integración continua como base. La integración continua (CI) es una práctica de desarrollo que consiste en fusionar los cambios de código en un repositorio compartido de forma frecuente, generalmente varias veces al día. Cada integración desencadena un proceso automatizado que compila el código, ejecuta pruebas unitarias y de integración, y genera informes sobre posibles fallos. Esto permite detectar y corregir errores de manera temprana, evitando que se acumulen problemas en etapas posteriores del desarrollo.

Automatización del despliegue. La automatización es un pilar fundamental en el despliegue de aplicaciones, ya que elimina la intervención manual en tareas repetitivas y propensas a errores. Herramientas especializadas permiten definir pipelines de despliegue que incluyen etapas como la construcción del artefacto, la ejecución de pruebas, la aprobación de cambios y la implementación en los entornos correspondientes. Esta automatización asegura que cada despliegue siga un flujo estandarizado, reduciendo la variabilidad y mejorando la trazabilidad de las versiones.

Entornos de despliegue. En la Administración General del Estado, los despliegues suelen realizarse en múltiples entornos, cada uno con un propósito específico. El entorno de desarrollo es donde los programadores trabajan y prueban sus cambios. El entorno de preproducción replica las condiciones del entorno productivo para validar el software antes de su liberación. Finalmente, el entorno de producción es donde el sistema está disponible para los usuarios finales. La gestión adecuada de estos entornos es crucial para evitar conflictos y garantizar la coherencia entre ellos.

Pruebas en integración continua. Las pruebas automatizadas son un componente esencial de la integración continua. Incluyen pruebas unitarias, que verifican el funcionamiento de componentes individuales; pruebas de integración, que aseguran que los módulos interactúan correctamente; y pruebas de aceptación, que validan que el sistema cumple con los requisitos funcionales. Estas pruebas se ejecutan automáticamente en cada integración, proporcionando retroalimentación inmediata a los desarrolladores y reduciendo el riesgo de introducir errores en el código.

Despliegue continuo y entrega continua. Mientras que la integración continua se centra en la validación automática del código, el despliegue continuo (CD) va un paso más allá al automatizar la liberación del software en entornos productivos. La entrega continua, por su parte, automatiza el proceso hasta el entorno de preproducción, pero requiere una aprobación manual para el despliegue final. Ambas prácticas buscan acelerar la entrega de valor al usuario, manteniendo al mismo tiempo altos estándares de calidad y seguridad.

Herramientas y estándares. En la Administración General del Estado, el despliegue de aplicaciones e integración continua se apoya en herramientas como Jenkins, GitLab CI/CD o Azure DevOps, que permiten orquestar los pipelines de construcción y despliegue. Además, se siguen estándares como ISO/IEC 12207 y Real Decreto 405/2023, que establecen directrices para la gestión del ciclo de vida del software, incluyendo la construcción, despliegue y documentación de los sistemas.

🧩 Elementos esenciales

• Integración continua (CI): Práctica que automatiza la construcción y prueba del código cada vez que se integra un cambio en el repositorio.
• Despliegue automatizado: Proceso que utiliza herramientas para instalar y configurar el software en los entornos correspondientes sin intervención manual.
• Pipelines de despliegue: Secuencia automatizada de etapas que incluye construcción, pruebas, aprobación y liberación del software.
• Entornos de despliegue: Espacios diferenciados (desarrollo, preproducción, producción) donde se valida y libera el software antes de su uso final.
• Pruebas automatizadas: Conjunto de pruebas (unitarias, integración, aceptación) que se ejecutan automáticamente para validar el código.
• Despliegue continuo (CD): Automatización completa del proceso de liberación del software hasta el entorno de producción.
• Entrega continua: Automatización del proceso hasta el entorno de preproducción, con aprobación manual para el despliegue final.
• Herramientas de CI/CD: Software como Jenkins, GitLab CI/CD o Azure DevOps que orquestan los pipelines de integración y despliegue.
• Trazabilidad: Capacidad de rastrear cada cambio y versión del software desde su desarrollo hasta su despliegue en producción.
• Estándares aplicables: Normativas como ISO/IEC 12207 y Real Decreto 405/2023 que regulan los procesos de construcción y despliegue en la AGE.

🧠 Recuerda

• El despliegue de aplicaciones busca trasladar el software a entornos operativos de forma segura y eficiente.
• La integración continua automatiza la validación del código para detectar errores de manera temprana.
• La automatización reduce errores humanos y acelera la entrega de versiones estables.
• Los entornos de despliegue (desarrollo, preproducción, producción) deben gestionarse de forma coherente.
• Las pruebas automatizadas son esenciales para garantizar la calidad del software en cada integración.
• El despliegue continuo y la entrega continua son prácticas clave en entornos DevOps.
• Herramientas como Jenkins o GitLab CI/CD son fundamentales para implementar pipelines de despliegue.
• Los estándares ISO/IEC 12207 y Real Decreto 405/2023 establecen directrices para estos procesos en la AGE.
• La trazabilidad de los cambios es crucial para mantener la coherencia y seguridad del sistema.
• La colaboración entre equipos de desarrollo y operaciones es esencial para el éxito del despliegue.

4. Dev-Ops

4. Dev-Ops

🎯 Idea clave

• Dev-Ops es una cultura de colaboración que integra los equipos de desarrollo y operaciones para mejorar la entrega continua de software.
• Su objetivo principal es acortar el ciclo de vida del desarrollo, garantizando calidad y seguridad en los sistemas.
• Se basa en la automatización de procesos para reducir errores humanos y acelerar despliegues.
• Promueve la monitorización continua para detectar y resolver incidencias de forma proactiva.
• Incluye prácticas como integración continua, entrega continua y despliegue continuo (CI/CD).
• Se alinea con los principios de agilidad y mejora continua en la Administración General del Estado.

📚 Desarrollo

Definición y alcance. Dev-Ops es un enfoque metodológico que busca unificar el desarrollo de software (Dev) y las operaciones de TI (Ops) mediante la colaboración, la automatización y la monitorización. En la Administración General del Estado, este modelo se aplica para optimizar la entrega de sistemas, garantizando que los servicios digitales sean fiables, seguros y alineados con las necesidades de los ciudadanos y las unidades administrativas.

Automatización de procesos. La automatización es un pilar fundamental de Dev-Ops, ya que permite eliminar tareas manuales repetitivas y propensas a errores. Esto incluye la construcción de código, las pruebas automatizadas, el despliegue en entornos y la gestión de configuraciones. La automatización no solo acelera los ciclos de desarrollo, sino que también mejora la consistencia y la trazabilidad de los cambios, aspectos críticos en entornos administrativos donde la transparencia y el cumplimiento normativo son prioritarios.

Integración y entrega continua (CI/CD). Dev-Ops se sustenta en prácticas como la integración continua (CI), que implica la fusión frecuente de cambios de código en un repositorio central, seguida de pruebas automatizadas. La entrega continua (CD) extiende este concepto, permitiendo que el software esté siempre en un estado desplegable. En la AGE, esto facilita la implementación de actualizaciones y mejoras sin interrumpir los servicios públicos, cumpliendo con los plazos y requisitos establecidos en los proyectos tecnológicos.

Cultura de colaboración. Dev-Ops no es solo una colección de herramientas, sino una cultura organizativa que fomenta la comunicación y la responsabilidad compartida entre equipos. En la Administración, esto implica romper silos tradicionales entre desarrolladores, administradores de sistemas y otros actores, promoviendo un enfoque multidisciplinar. La colaboración se extiende también a la retroalimentación continua, donde los equipos de operaciones aportan datos sobre el rendimiento y la estabilidad de los sistemas, que son utilizados para mejorar el desarrollo.

Monitorización y feedback. La monitorización continua es esencial para detectar problemas en tiempo real y garantizar la disponibilidad de los servicios. Dev-Ops incorpora herramientas de monitorización que recopilan métricas sobre el rendimiento, la seguridad y la experiencia de usuario. Estos datos se utilizan para generar feedback rápido, permitiendo a los equipos corregir incidencias antes de que afecten a los usuarios finales. En el contexto de la AGE, esto es especialmente relevante para garantizar la continuidad de servicios críticos.

Seguridad y cumplimiento. Dev-Ops integra la seguridad desde las primeras fases del desarrollo, un enfoque conocido como DevSecOps. Esto implica la incorporación de pruebas de seguridad automatizadas, la gestión de vulnerabilidades y el cumplimiento de normativas como el Esquema Nacional de Seguridad (ENS). En la Administración, este enfoque garantiza que los sistemas cumplan con los requisitos legales y técnicos, protegiendo la información sensible y los datos de los ciudadanos.

Herramientas y estándares. La implementación de Dev-Ops en la AGE se apoya en herramientas como sistemas de control de versiones (Git), plataformas de integración continua (Jenkins, GitLab CI), contenedores (Docker) y orquestadores (Kubernetes). Además, se alinea con estándares como ISO/IEC 12207 y Real Decreto 405/2023, que establecen marcos para la gestión del ciclo de vida del software en el sector público.

🧩 Elementos esenciales

• Cultura Dev-Ops: Enfoque colaborativo que une desarrollo y operaciones para mejorar la entrega de software.
• Automatización: Eliminación de tareas manuales en construcción, pruebas y despliegue para reducir errores.
• Integración continua (CI): Fusión frecuente de código en un repositorio central con pruebas automatizadas.
• Entrega continua (CD): Mantenimiento del software en estado desplegable en todo momento.
• Despliegue continuo: Automatización del despliegue en entornos de producción de forma segura y controlada.
• Monitorización continua: Recopilación de métricas en tiempo real para detectar y resolver incidencias.
• DevSecOps: Integración de la seguridad en todas las fases del ciclo de vida del desarrollo.
• Herramientas clave: Git, Jenkins, Docker, Kubernetes y plataformas de CI/CD.
• Estándares aplicables: ISO/IEC 12207 y Real Decreto 405/2023 para la gestión del ciclo de vida en la AGE.
• Feedback continuo: Uso de datos de monitorización para mejorar el desarrollo y las operaciones.
• Colaboración multidisciplinar: Rompimiento de silos entre equipos para una responsabilidad compartida.
• Cumplimiento normativo: Garantía de que los sistemas cumplen con requisitos legales y técnicos.

🧠 Recuerda

• Dev-Ops no es solo tecnología, sino una cultura de colaboración entre desarrollo y operaciones.
• La automatización es clave para reducir errores y acelerar los ciclos de entrega.
• CI/CD permite mantener el software en un estado desplegable en todo momento.
• La monitorización continua es esencial para garantizar la disponibilidad y el rendimiento.
• DevSecOps integra la seguridad desde las primeras fases del desarrollo.
• Las herramientas como Git, Jenkins y Docker son fundamentales para implementar Dev-Ops.
• Los estándares ISO/IEC 12207 y Real Decreto 405/2023 guían la aplicación de Dev-Ops en la AGE.
• La colaboración entre equipos mejora la eficiencia y la calidad de los sistemas.
• El feedback continuo permite corregir incidencias antes de que afecten a los usuarios.
• Dev-Ops alinea la entrega de software con los principios de agilidad y mejora continua.

5. Estándares de documentación

5. Estándares de documentación

🎯 Idea clave

• Los estándares de documentación en la Administración General del Estado garantizan la uniformidad y calidad en la creación de manuales y guías técnicas.
• La normativa aplicable incluye el Real Decreto 405/2023, la ISO/IEC 12207 y la ISO/IEC 25000, que establecen requisitos para la documentación de sistemas.
• La documentación debe ser clara, accesible y adaptada a los distintos perfiles de usuarios, tanto técnicos como no técnicos.
• Los estándares facilitan la mantenibilidad y escalabilidad de los sistemas al proporcionar información estructurada y actualizada.
• La IEEE 1063 es una referencia clave para la elaboración de manuales técnicos y de usuario en entornos de desarrollo de software.
• La documentación debe integrarse en el ciclo de vida del sistema, desde su construcción hasta su despliegue y mantenimiento.

📚 Desarrollo

Base normativa. Los estándares de documentación en la Administración General del Estado se sustentan en el Real Decreto 405/2023, que regula los requisitos mínimos para la documentación de sistemas de información. Este marco legal se complementa con normas internacionales como la ISO/IEC 12207, que establece procesos para el ciclo de vida del software, y la ISO/IEC 25000, centrada en la calidad del producto software. Estas normas aseguran que la documentación cumpla con criterios de claridad, completitud y utilidad.

Objetivo principal. La finalidad de los estándares de documentación es proporcionar información estructurada y homogénea que facilite la comprensión, el uso y el mantenimiento de los sistemas. En el ámbito de la AGE, esto es especialmente relevante debido a la diversidad de usuarios, que incluyen desde personal técnico hasta usuarios finales sin conocimientos especializados. La documentación debe ser accesible y adaptada a cada perfil, evitando ambigüedades y garantizando la coherencia en la información proporcionada.

Integración en el ciclo de vida. La documentación no es un proceso aislado, sino que debe integrarse en todas las fases del ciclo de vida del sistema. Desde la construcción del sistema hasta su despliegue y mantenimiento, cada etapa debe generar documentación actualizada y alineada con los estándares establecidos. Esto incluye la elaboración de manuales técnicos, guías de usuario y registros de cambios, que deben ser revisados y validados periódicamente para asegurar su vigencia.

Estructura y contenido. Los estándares definen una estructura clara para la documentación, que debe incluir, al menos, los siguientes elementos: descripción del sistema, funcionalidades, requisitos técnicos, procedimientos de instalación y configuración, y guías de resolución de problemas. La IEEE 1063 proporciona directrices específicas para la redacción de manuales técnicos y de usuario, estableciendo formatos, niveles de detalle y criterios de accesibilidad.

Accesibilidad y usabilidad. La documentación debe ser accesible para todos los usuarios, independientemente de sus capacidades técnicas. Esto implica el uso de un lenguaje claro y conciso, evitando tecnicismos innecesarios en los manuales dirigidos a usuarios finales. Además, se deben seguir pautas de accesibilidad, como las establecidas en la normativa vigente, para garantizar que la información sea comprensible y utilizable por personas con discapacidad.

Actualización y mantenimiento. La documentación debe ser un documento vivo, que se actualice de manera continua para reflejar los cambios en el sistema. Los estándares exigen la implementación de procesos de revisión y validación, que aseguren que la información proporcionada sea siempre precisa y relevante. Esto incluye la gestión de versiones y la notificación de cambios a los usuarios afectados.

Herramientas y formatos. Los estándares no imponen herramientas específicas, pero sí recomiendan el uso de formatos estandarizados que faciliten la interoperabilidad y el intercambio de información. Esto incluye el uso de lenguajes de marcado como XML o formatos abiertos como PDF/A, que garantizan la preservación a largo plazo de la documentación. Además, se fomenta el uso de plantillas y guías de estilo para mantener la coherencia en la presentación de la información.

🧩 Elementos esenciales

• Real Decreto 405/2023: Norma que regula los requisitos mínimos para la documentación de sistemas en la AGE, estableciendo criterios de calidad y accesibilidad.
• ISO/IEC 12207: Norma internacional que define procesos para el ciclo de vida del software, incluyendo la documentación como parte integral del desarrollo.
• ISO/IEC 25000: Estándar centrado en la calidad del producto software, que incluye requisitos para la documentación técnica y de usuario.
• IEEE 1063: Guía para la elaboración de manuales técnicos y de usuario, que establece formatos, estructura y niveles de detalle.
• Manuales técnicos: Documentación dirigida a personal especializado, que incluye información detallada sobre la arquitectura, configuración y mantenimiento del sistema.
• Manuales de usuario: Guías orientadas a usuarios finales, con instrucciones claras y accesibles para el uso del sistema.
• Accesibilidad: Requisito fundamental en la documentación, que garantiza que la información sea comprensible y utilizable por todos los usuarios, incluyendo personas con discapacidad.
• Actualización continua: Proceso de revisión y validación periódica de la documentación para asegurar su vigencia y precisión.
• Gestión de versiones: Control de las distintas versiones de la documentación, que permite registrar cambios y notificar a los usuarios afectados.
• Lenguaje claro: Uso de un lenguaje sencillo y conciso en los manuales de usuario, evitando tecnicismos innecesarios.
• Formatos estandarizados: Uso de formatos como XML o PDF/A, que facilitan la interoperabilidad y la preservación a largo plazo de la documentación.
• Plantillas y guías de estilo: Herramientas que aseguran la coherencia en la presentación y estructura de la documentación.

🧠 Recuerda

• Los estándares de documentación son obligatorios en la AGE y se rigen por el Real Decreto 405/2023 y normas internacionales como la ISO/IEC 12207.
• La documentación debe ser clara, accesible y adaptada a los distintos perfiles de usuarios, desde técnicos hasta usuarios finales.
• La IEEE 1063 es una referencia clave para la elaboración de manuales técnicos y de usuario.
• La documentación debe integrarse en todas las fases del ciclo de vida del sistema, desde su construcción hasta su mantenimiento.
• Es fundamental mantener la documentación actualizada y gestionar las versiones para reflejar los cambios en el sistema.
• La accesibilidad es un requisito esencial, que garantiza que la información sea comprensible para todos los usuarios.
• Los formatos estandarizados y las plantillas facilitan la coherencia y la interoperabilidad de la documentación.
• La documentación no es un proceso aislado, sino una parte integral del desarrollo y mantenimiento de los sistemas.

6. Manuales de usuario y manuales técnicos

6. Manuales de usuario y manuales técnicos

🎯 Idea clave

• Los manuales de usuario son documentos destinados a facilitar el uso del sistema a los usuarios finales, explicando funcionalidades y procedimientos de manera accesible.
• Los manuales técnicos están orientados al personal especializado, detallando aspectos internos del sistema como arquitectura, configuración o resolución de problemas.
• Ambos tipos de manuales deben cumplir con estándares de documentación establecidos para garantizar claridad, precisión y utilidad.
• La elaboración de estos manuales forma parte del ciclo de vida del desarrollo de sistemas en la Administración General del Estado.
• Su estructura y contenido deben adaptarse al perfil del destinatario, evitando tecnicismos innecesarios en los manuales de usuario.
• La actualización periódica de los manuales es esencial para reflejar cambios en el sistema o en los procedimientos de uso.

📚 Desarrollo

Finalidad y destinatarios. Los manuales de usuario y manuales técnicos cumplen funciones distintas dentro del ciclo de vida de un sistema. Mientras los manuales de usuario se dirigen a los usuarios finales, con el objetivo de guiarles en el uso cotidiano del sistema, los manuales técnicos están diseñados para administradores, desarrolladores o personal de soporte, proporcionando información detallada sobre la estructura interna, configuración y mantenimiento del sistema.

Normativa aplicable. En la Administración General del Estado, la elaboración de estos manuales se rige por estándares como la norma ISO/IEC 12207 y el Real Decreto 405/2023, que establecen directrices para la documentación de sistemas. Estos marcos normativos exigen que los manuales sean claros, completos y actualizados, asegurando que la información sea accesible y útil para sus destinatarios. Además, la norma IEEE 1063 proporciona pautas específicas para la redacción de documentación técnica.

Contenido del manual de usuario. Este tipo de manual debe incluir una descripción general del sistema, instrucciones paso a paso para realizar tareas comunes, ejemplos prácticos y soluciones a problemas frecuentes. Es fundamental que el lenguaje empleado sea sencillo y libre de tecnicismos, priorizando la claridad y la usabilidad. También puede incorporar capturas de pantalla, diagramas o flujos de trabajo para facilitar la comprensión.

Contenido del manual técnico. A diferencia del manual de usuario, el manual técnico profundiza en aspectos como la arquitectura del sistema, los requisitos de hardware y software, los procedimientos de instalación y configuración, y las guías de resolución de incidencias. Este documento debe ser preciso y detallado, ya que su objetivo es servir de referencia para el personal técnico encargado del mantenimiento y la operación del sistema.

Estructura y formato. Ambos tipos de manuales deben seguir una estructura lógica y coherente. Es recomendable incluir un índice detallado, una introducción que explique el propósito del documento, y secciones claramente diferenciadas. El uso de encabezados, listas y elementos visuales como tablas o diagramas puede mejorar la legibilidad. Además, es importante que los manuales estén disponibles en formatos accesibles, como PDF o HTML, para facilitar su consulta.

Actualización y mantenimiento. Los manuales no son documentos estáticos, sino que deben actualizarse periódicamente para reflejar cambios en el sistema, correcciones de errores o mejoras en los procedimientos. La gestión de versiones es clave para garantizar que los usuarios y el personal técnico siempre dispongan de la información más reciente. En este sentido, las herramientas de control de versiones y gestión de documentación pueden ser de gran utilidad.

Integración con otros procesos. La elaboración de manuales está estrechamente ligada a otros procesos del ciclo de vida del sistema, como el desarrollo, el despliegue y la formación. Por ejemplo, los manuales técnicos pueden servir de base para la formación del personal de soporte, mientras que los manuales de usuario pueden complementarse con materiales formativos para los usuarios finales. Esta integración asegura la coherencia y la eficacia de la documentación.

🧩 Elementos esenciales

• Manual de usuario: Documento orientado a usuarios finales que explica cómo utilizar el sistema de manera sencilla y práctica.
• Manual técnico: Documento dirigido a personal especializado que detalla aspectos internos del sistema, como arquitectura, configuración y mantenimiento.
• Normativa aplicable: Estándares como ISO/IEC 12207 y Real Decreto 405/2023 que regulan la elaboración de documentación en la Administración General del Estado.
• Contenido del manual de usuario: Instrucciones paso a paso, ejemplos prácticos, soluciones a problemas frecuentes y lenguaje accesible.
• Contenido del manual técnico: Arquitectura del sistema, requisitos técnicos, procedimientos de instalación y configuración, y guías de resolución de incidencias.
• Estructura: Índice detallado, introducción, secciones diferenciadas y uso de elementos visuales para mejorar la legibilidad.
• Actualización: Proceso continuo para reflejar cambios en el sistema, correcciones o mejoras, garantizando que la información esté siempre actualizada.
• Formatos accesibles: Disponibilidad en PDF, HTML u otros formatos que faciliten la consulta y la accesibilidad.
• Integración con formación: Los manuales pueden complementarse con materiales formativos para usuarios y personal técnico.
• Herramientas de gestión: Uso de herramientas de control de versiones y gestión de documentación para mantener la coherencia y la trazabilidad.

🧠 Recuerda

• Los manuales de usuario y técnicos tienen destinatarios y objetivos distintos, por lo que su contenido debe adaptarse a cada perfil.
• La claridad y la precisión son fundamentales en ambos tipos de manuales, aunque el lenguaje varía según el público objetivo.
• Los estándares como ISO/IEC 12207 y Real Decreto 405/2023 establecen directrices para la elaboración de documentación en la Administración General del Estado.
• La estructura de los manuales debe ser lógica y coherente, con secciones claramente diferenciadas y elementos visuales que faciliten la comprensión.
• La actualización periódica de los manuales es esencial para reflejar cambios en el sistema o en los procedimientos.
• Los manuales técnicos deben incluir información detallada sobre la arquitectura, configuración y mantenimiento del sistema.
• Los manuales de usuario deben evitar tecnicismos y priorizar ejemplos prácticos y soluciones a problemas frecuentes.
• La integración con otros procesos, como la formación, asegura la coherencia y la eficacia de la documentación.
• El uso de herramientas de gestión de documentación y control de versiones es clave para mantener la trazabilidad y la actualización de los manuales.

7. Formación de usuarios y personal técnico: métodos y materiales

7. Formación de usuarios y personal técnico: métodos y materiales

🎯 Idea clave

• La formación en la Administración General del Estado se estructura para garantizar la correcta adopción de sistemas por usuarios y técnicos.
• Los métodos de formación deben adaptarse a los perfiles de los destinatarios, diferenciando entre usuarios finales y personal técnico.
• Los materiales formativos se elaboran siguiendo estándares de documentación técnica y de usuario establecidos en el ciclo de vida del sistema.
• La formación técnica prioriza el conocimiento de los entornos de construcción, despliegue e integración continua utilizados en la AGE.
• Los manuales de usuario y técnicos constituyen la base documental para la formación, complementados con sesiones prácticas y demostrativas.
• La evaluación de la formación asegura la comprensión de los procedimientos y la capacidad de resolución de incidencias básicas.

📚 Desarrollo

Objetivo de la formación. La formación en la Administración General del Estado busca capacitar a los usuarios finales en el uso eficiente de los sistemas desplegados, así como al personal técnico en su mantenimiento, despliegue y evolución. Este proceso se integra en el ciclo de vida del sistema, asegurando que todos los actores conozcan sus roles y responsabilidades en cada fase.

Diferenciación de perfiles. Los métodos y materiales formativos se diseñan en función del perfil del destinatario. Los usuarios finales reciben formación centrada en el manejo funcional del sistema, mientras que el personal técnico se forma en aspectos como la construcción del código, la gestión de entornos de despliegue y la integración continua. Esta segmentación garantiza que cada grupo adquiera los conocimientos necesarios para su ámbito de actuación.

Materiales formativos. Los manuales de usuario y técnicos son la piedra angular de la formación. Los manuales de usuario explican de forma clara y accesible las funcionalidades del sistema, mientras que los manuales técnicos detallan aspectos como la arquitectura, los flujos de datos y los procedimientos de despliegue. Ambos tipos de documentación se elaboran siguiendo estándares como ISO/IEC 12207 y IEEE 1063, que establecen criterios de claridad, estructura y completitud.

Métodos de formación. La formación combina sesiones teóricas con prácticas demostrativas. Para los usuarios finales, se emplean talleres presenciales o virtuales que simulan escenarios reales de uso. El personal técnico, por su parte, recibe formación en entornos de construcción y despliegue, utilizando herramientas como pipelines de integración continua y plataformas de DevOps. Estas sesiones incluyen ejercicios prácticos para familiarizarse con los flujos de trabajo y las herramientas específicas de la AGE.

Evaluación y seguimiento. La eficacia de la formación se evalúa mediante pruebas prácticas y cuestionarios que miden la comprensión de los contenidos. En el caso del personal técnico, se verifica su capacidad para realizar tareas como el despliegue de aplicaciones o la resolución de incidencias en entornos controlados. Para los usuarios finales, se evalúa su competencia en el uso de las funcionalidades básicas y avanzadas del sistema.

Actualización continua. Los materiales formativos se actualizan periódicamente para reflejar cambios en los sistemas, nuevas versiones de software o modificaciones en los procedimientos. Esta actualización es especialmente relevante en entornos dinámicos como los de integración continua, donde las herramientas y metodologías evolucionan con frecuencia. La formación no se limita a una fase inicial, sino que se concibe como un proceso continuo a lo largo del ciclo de vida del sistema.

Normativa aplicable. La formación en la AGE se enmarca en el cumplimiento de normativas como el Real Decreto 405/2023, que regula aspectos relacionados con la gestión de sistemas y tecnologías de la información. Además, se alinea con estándares internacionales como ISO/IEC 25000, que establece requisitos de calidad para los sistemas y su documentación asociada.

🧩 Elementos esenciales

• Perfiles formativos: Diferenciación entre usuarios finales y personal técnico, con contenidos adaptados a cada grupo.
• Manuales de usuario: Documentación orientada a explicar las funcionalidades del sistema de forma accesible y práctica.
• Manuales técnicos: Documentación detallada sobre la arquitectura, despliegue y mantenimiento del sistema, dirigida a personal técnico.
• Estándares de documentación: Normas como ISO/IEC 12207 e IEEE 1063 que regulan la estructura y calidad de los materiales formativos.
• Métodos prácticos: Talleres y sesiones demostrativas que combinan teoría y práctica para garantizar la comprensión.
• Entornos de formación: Plataformas y herramientas utilizadas para simular escenarios reales de uso y despliegue.
• Evaluación de competencias: Pruebas prácticas y cuestionarios para medir la eficacia de la formación y la adquisición de conocimientos.
• Actualización de materiales: Proceso continuo de revisión y actualización de los contenidos formativos para reflejar cambios en los sistemas.
• Integración con DevOps: Formación en herramientas y flujos de trabajo de integración continua y despliegue automatizado.
• Cumplimiento normativo: Alineación con el Real Decreto 405/2023 y otros estándares aplicables en la AGE.

🧠 Recuerda

• La formación en la AGE es un proceso diferenciado según el perfil del destinatario.
• Los manuales de usuario y técnicos son la base documental de la formación.
• Los estándares ISO/IEC 12207 e IEEE 1063 regulan la calidad de los materiales formativos.
• La formación técnica incluye el manejo de entornos de construcción, despliegue e integración continua.
• Las sesiones prácticas son esenciales para garantizar la comprensión de los contenidos.
• La evaluación de la formación asegura que los usuarios y técnicos adquieren las competencias necesarias.
• Los materiales formativos deben actualizarse periódicamente para reflejar cambios en los sistemas.
• La formación no es un evento puntual, sino un proceso continuo a lo largo del ciclo de vida del sistema.
• El Real Decreto 405/2023 establece el marco normativo aplicable a la formación en la AGE.
• La formación en DevOps es clave para el personal técnico responsable del despliegue y mantenimiento de sistemas.