Subdirección de las Tecnologías de la Información y Comunicaciones

Área de Gobernanza y Calidad

Contenidos

Resumen

Versión: v01r00
Fecha publicación: 3 de mayo de 2022
Entrada en vigor desde: 3 de mayo de 2022

Cumplimiento normativo

Las normas expuestas son de obligado cumplimiento. La STIC podrá estudiar los casos excepcionales los cuales serán gestionados a través de los responsables del proyecto correspondiente y autorizados por el Área de Gobernanza de la STIC. Asimismo cualquier aspecto no recogido en estas normas deberá regirse en primera instancia por las guías técnicas correspondientes al esquema nacional de seguridad y esquema nacional de interoperabilidad según correspondencia y en su defecto a los marcos normativos y de desarrollo software establecidos por la Junta de Andalucía, debiendo ser puesto de manifiesto ante la STIC.

La STIC se reserva el derecho a la modificación de la norma sin previo aviso, tras lo cual, notificará del cambio a los actores implicados para su adopción inmediata según la planificación de cada proyecto.

En el caso de que algún actor considere conveniente y/o necesario el incumplimiento de alguna de las normas y/o recomendaciones, deberá aportar previamente la correspondiente justificación fehaciente documentada de la solución alternativa propuesta, así como toda aquella documentación que le sea requerida por la STIC para proceder a su validación técnica.

Contacto Dpto: Oficina de Calidad

Histórico de cambios

Los cambios en la normativa vendrán acompañados de un registro de las modificaciones. De este modo se podrá realizar un seguimiento y consultar su evolución.

Versión

v01r01

Fecha publicación

3 de mayo de 2022

Fecha entrada en vigor

3 de mayo de 2022

Alcance

Versión inicial

Introducción

Como de todos es sabido, la correcta documentación de los diferentes aspectos relacionados con un proyecto es una parte esencial para el conocimiento de la aplicaciones. Facilita su mantenimiento y mejora la eficiencia de la transferencia de conocimiento.

Este artículo pretende ofrecer una guía para la entrega de documentación por parte del proveedor. En él se describe de forma general los documentos solicitados por las diferentes áreas, así como su formato. No obstante, cabe señalar que, como en el caso de otros entregables, la documentación requerida se irá consensuando a lo largo de la vida del proyecto.

La herramienta para la gestión de los proyectos será JIRA. En cuanto a la organización de la documentación y la gestión del conocimiento, se utilizará Confluence. Además, las herramientas de integración continua nos ayudarán en uno de nuestros principales objetivos: la detección temprana de errores.

Documentación a entregar

Documentación proyectos Agile

Con este apartado se pretende abordar la cuestión de la documentación a entregar en los proyectos gestionados bajo un marco de metodología ágil (Scrum).

De todos es sabido que la elaboración del Definition of Done es una de las tareas en la que se verá involucrado el equipo Scrum. A este respecto, la SMO ha publicado un DoD estándar con el fin de servir de referencia en su redacción.

A continuación se listan una serie de entregables. Se especifica también el formato de los mismos. El uso de cualquier otro medio o formato de entrega deberá ser previamente consensuado con la STIC y definido en el DoR y/o DoD del proyecto.

Entregable	Etapa a entregar	Obligatoriedad	Ubicación	Comentarios
Definición de requisitos. Historias de Usuario	Sprint Planning (DoR)	Obligatorio	JIRA	Las historias de usuarios y las pruebas que la validan son el pilar sobre el que sostener el conocimiento funcional de las diferentes aplicaciones. Para consultar en detalle cómo se han de entregar, se puede consultar el artículo Requisitos y pruebas en proyectos ágiles.
Arquitectura del sistema		Obligatorio	Confluence
Interoperabilidad con otros sistemas	Durante el Sprint (DoD)	Obligatorio en caso de que disponga interoperabilidad con otros sistemas/front y back	Confluence	Actualmente la OTI utiliza Confluence para la generación y gestión de la documentación. Se puede consultar la información relativa al proceso de integración en el siguiente enlace.
Interfaz de usuario y Navegación: Maqueta o Prototipo gráfico	Durante el Sprint (DoD)	Obligatorio	Confluence	Se acuerda al inicio del proyecto
Manual de usuario	Durante el Sprint (DoD)	Obligatorio	Confluence
Casos de prueba: precondiciones y escenarios	Durante el Sprint (DoD)	Obligatorio	GIT/JIRA	Los casos de pruebas y sus precondiciones se redactarán usando el lenguaje Gherkin. Las pruebas se agruparán en archivos de extensión .feature. Los .feature se adjuntarán a la historia de usuario correspondiente. Una vez validados, se subirán a GIT siguiendo la normativa. La redacción de pruebas en este formato y la utilización de Gherkin como lenguaje, se extiende a todas las pruebas funcionales (vayan a ser automatizadas o no). Para consultar en detalle cómo se han de entregar, se puede consultar el artículo Requisitos y pruebas en proyectos ágiles.

Documentación proyectos modelo Cascada

Para este tipo de proyectos, la documentación a entregar y su formato puede variar. A continuación se presentan las diferentes opciones con las que se trabaja.

Proyectos nuevos

Ubicación: Confluence
Entregable	Etapa a entregar	Obligatoriedad	Comentarios
EAP	Antes de la entrega, como mínimo 3 semanas antes	Obligatorio	El desglose de la información obligatoria u opcional que puede contener este archivo se ha indicado en la tabla que aparece a continuación a ésta. Su ubicación dentro del espacio de Confluence deberá ser consensuar con el jefe de proyecto. También es importante tener en cuenta que existen varias versiones de las plantillas. Se deberá acordar con la OCa la versión de la plantilla a utilizar. Plantilla a utilizar en función del proyecto Descarga de la plantilla NOTA: Para más detalle, se puede consultar la normativa pulsando *Aquí.*
Modelo de Procesos de Negocio	Análisis del Sistema	Opcional	Se debe documentar en Confluence en el apartado indicado por la OTI. Modelo de proceso de negocio Software (Opcional). Modelo de proceso de negocio Interoperabilidad (Opcional para nuevo desarrollo).
Interfaces de Usuario y Navegación	Análisis del Sistema	Obligatorio	Pantallas (en la plantilla de arquitectura generada dentro del espacio del proyecto). Informes y listados (en la plantilla de arquitectura generada dentro del espacio del proyecto). Maqueta o prototipo gráfico (se ha de acordar al inicio del proyecto).
Arquitectura lógica y física del sistema	Diseño del sistema	Obligatorio	Plantilla de Arquitectura publicada en cada espacio.
Modelo de Clases Lógico y físico	Diseño del Sistema	Obligatorio	Plantilla de Arquitectura publicada en cada espacio.
Modelo de Datos Lógico y físico	Diseño del Sistema	Obligatorio	Plantilla de Arquitectura publicada en cada espacio.
Interfaz a través de servicios DS	Etapa de Análisis y diseño	Obligatorio en caso de que disponga de una interfaz a través de servicios	La información detallada sobre ellas es tratada por la OTI (Normativa disponible en el siguiente enlace y Proceso de Integración disponible en el siguiente enlace).
Provisión de servicios DS	Etapa de Análisis y diseño	Obligatorio en caso de que disponga de provisión de servicios	Actualmente la OTI trabaja con confluence. Se puede consultar la información relativa al proceso de integración en el siguiente enlace.
Consumo de servicios DS	Etapa de Análisis y diseño	Obligatorio en caso de que disponga de consumo de servicios	Actualmente la OTI trabaja con confluence. Se puede consultar la información relativa al proceso de integración en el siguiente enlace.

Ubicación: Confluence
Entregable: EAP			Obligatoriedad	Comentarios
Información del aplicativo		Glosario	Opcional
		Constantes para la generación de la documentación	Obligatorio
		Control de cambios	Obligatorio
		Participantes	Ver comentarios	Es obligatorio completar el apartado de participantes para los aplicativos de explotación de datos, para los aplicativos software es un apartado opcional.
Aplicativo Software	Definición de requisitos	Objetivos del Sistema	Obligatorio
	Definición de requisitos	Catálogo de Requisitos	Obligatorio
	Análisis del Sistema	Modelo de Subsistemas	Obligatorio
		Catálogo de Actores	Obligatorio
		Modelo de Casos de Uso	Obligatorio
		Casos de Prueba	Obligatorio
		Prueba de autorización	Obligatorio
		Smoke test	Obligatorio

Proyectos mantenimiento

Es importante resaltar que, para el caso de los proyectos que están en mantenimiento, la documentación y el formato de entrega seguirán las pautas acordadas al comienzo del proyecto.

Ubicación: Confluence
Entregable	Etapa a entregar	Obligatoriedad	Comentarios
EAP	Antes de la entrega, como mínimo 3 semanas antes	Obligatorio	El desglose de la información obligatoria u opcional que puede contener este archivo se ha indicado en la tabla que aparece a continuación a ésta. Su ubicación dentro del espacio de Confluence deberá ser consensuar con el jefe de proyecto. Plantilla a utilizar en función del proyecto. Descarga de la plantilla. NOTA: Para más detalle, se puede consultar la normativa pulsando *Aquí.*
Interfaz a través de servicios	Análisis y diseño (Antes de iniciar los desarrollos)	Obligatorio en caso de que disponga de una interfaz a través de servicios	La información detallada sobre ellas es tratada por la OTI (Normativa disponible en el siguiente enlace y Proceso de Integración disponible en el siguiente enlace).
Provisión de servicios	Análisis y diseño (Antes de iniciar los desarrollos)	Obligatorio en caso de que disponga de provisión de servicios	Actualmente la OTI trabaja con confluence. Se puede consultar la información relativa al proceso de integración en el siguiente enlace.
Consumo de servicios	Análisis y diseño (Antes de iniciar los desarrollos)	Obligatorio en caso de que disponga de consumo de servicios	Actualmente la OTI trabaja con confluence. Se puede consultar la información relativa al proceso de integración en el siguiente enlace.

Ubicación: Confluence
Entregable: EAP			Obligatoriedad	Comentarios
Información del aplicativo	Glosario		Opcional
	Constantes para la generación de la documentación		Obligatorio
	Control de cambios		Obligatorio
	Participantes		Ver comentarios	Es obligatorio completar el apartado de participantes para los aplicativos de explotación de datos, para los aplicativos software es un apartado opcional.
Aplicativo Software	Definición de requisitos	Objetivos del Sistema	Obligatorio
	Definición de requisitos	Catálogo de Requisitos	Obligatorio
	Análisis del Sistema	Modelo de Subsistemas	Obligatorio
		Catálogo de Actores	Obligatorio
		Modelo de Casos de Uso	Obligatorio
		Modelo de Clases Lógico	Obligatorio	Es importante tener en cuenta que el equipo de arquitectura podría consensuar con el proveedor el traslado esta información desde el archivo .eap a la plantilla de Confluence para continuar con su mantenimiento en este formato.
		Modelo de Datos Lógico	Obligatorio	Es importante tener en cuenta que el equipo de arquitectura podría consensuar con el proveedor el traslado esta información desde el archivo .eap a la plantilla de Confluence para continuar con su mantenimiento en este formato.
		Casos de Prueba	Obligatorio
		Prueba de autorización	Obligatorio
		Smoke test	Obligatorio
	Diseño del sistema	Arquitectura del sistema	Opcional	Es importante tener en cuenta que el equipo de arquitectura podría consensuar con el proveedor el traslado esta información desde el archivo .eap a la plantilla de Confluence para continuar con su mantenimiento en este formato.
		Modelo de clases físico	Opcional	Es importante tener en cuenta que el equipo de arquitectura podría consensuar con el proveedor el traslado esta información desde el archivo .eap a la plantilla de Confluence para continuar con su mantenimiento en este formato.
		Modelo de datos físico	Opcional	Es importante tener en cuenta que el equipo de arquitectura podría consensuar con el proveedor el traslado esta información desde el archivo .eap a la plantilla de Confluence para continuar con su mantenimiento en este formato.
Construcción del sistema			Opcional	Esta carpeta contendrá todos los elementos referentes a la construcción del sistema que se va a desarrollar. Se podrán usar los elementos de Enterprise Architect destinados a representar esta información. El contenido de esta carpeta no será revisado por la OCa, pero se recomienda que se incorpore la información asociada a la construcción del sistema para poder disponer de ella, tanto en caso de duda durante la revisión del resto de elementos, como en caso de que algún otro interesado del proyecto necesite consultarla.

Excepciones

Teniendo en cuenta que algunos proyectos se iniciaron hace bastante tiempo y que algunos de ellos tienen tendencia a desaparear y ser sustituidos o embebidos por otros, se diferencian dos bloques que agrupan distintos proyectos y en cada bloque se define y detalla la información que se ha de documentar en EA.

Para tener el detalle de cada una de las excepciones, se deberá consultar el siguiente enlace.

Documentación Adicional

Hay documentación que está relacionada más con un aspecto o actividad dentro del proyecto que con la metodología con la que se gestiona.

Pruebas de Carga

Ubicación: Confluence
Entregable	Etapa a entregar	Obligatoriedad	Comentarios
Plan de pruebas de carga		Obligatorio	Existe una plantilla en Confluence para la redacción del plan. Para la consultar cómo crearla, ir al apartado *Anexo II: Plantilla PPS* de la normativa de Pruebas de carga del sistema.

Ubicación: Git
Entregable	Etapa a entregar	Obligatoriedad	Comentarios
Script de lanzamiento de las pruebas		Obligatorio	Se entregará cualquier archivo que hay sido necesario para la ejecución de las pruebas, tal y como se indica en el apartado Entregables tras las pruebas de la de Pruebas de carga del sistema.

Árbol de páginas

Documentación del proyecto