Framework: pautas de redacción

En el Modelo Global de Soluciones, los recursos son elementos corporativos en los que se apoyan o con los que se crean las soluciones tecnológicas. Entre ellos se cuentan los activos, elementos de uso general o generalizable, que contribuyen a la estandarización y reutilización del desarrollo de software.

Un framework es un tipo específico de activo, que consiste en un conjunto de componentes, reglas y convenciones que se usan para desarrollar software de manera más rápida, recomendados para mejorar la eficiencia del proceso de desarrollo.

Para recoger la información acerca de los framework en el portal se utiliza el tipo de contenido Activo. A continuación, enumeramos los apartados principales de las fichas de este tipo de Activo y pautas específicas para su redacción.

Título

Prioriza la claridad en la identificación del framework.

• El título de la ficha del framework debe ser conciso y descriptivo de su función principal, con la forma general "Framework para..." o "Framework de..." seguido de la finalidad.
• El nombre identificativo del framework seguirá la convención: ada-fwk-[tipo de funcionalidad o ámbito] (ej: ada-fwk-ms) 
• El nombre identificativo del framework debe incluirse entre paréntesis al final del título.
• Se recomienda seguir una estructura similar a la siguiente (adaptando el lenguaje según sea necesario):
  • Framework para [finalidad principal] ([Nombre del Framework])

Descripción

Este apartado proporcionará una visión general clara y concisa del activo, su propósito, la tecnología en la que se basa y los principales beneficios que ofrece a los usuarios, utilizando un lenguaje accesible y bien estructurado.

Se ha de utilizar el campo Descripción, que contendrá lo siguiente:

• Comienza con una declaración concisa del activo: Identifica claramente qué es el activo y su tipo (por ejemplo, un framework de desarrollo).
• Indica la tecnología base (si aplica): Menciona la tecnología principal sobre la que se construye el activo (por ejemplo, basado en Angular).
• Describe el propósito principal y los casos de uso: Explica para qué se diseñó el activo y los tipos de aplicaciones o funcionalidades que facilita (pòr ejemplo, para construir microfrontends).
  Menciona el beneficio clave o la propuesta de valor: Resalta la principal ventaja que ofrece el activo a los usuarios (por ejemplo, simplificar la creación y facilitar el uso de la tecnología base).
  Explica el mecanismo principal para lograr el beneficio: Describe cómo el activo entrega su valor (por ejemplo, proporcionando una capa de abstracción con componentes y herramientas de alto nivel).
  Incluye los beneficios adicionales para los usuarios: Menciona otras ventajas que ofrece el activo (por ejemplo, permitir trabajar de manera más intuitiva y con menos código).
• Características principales o elementos que contiene.

¿A quién va dirigido?

Este apartado se incluirá en primer lugar en el campo Contenido utilizando el rótulo "¿A quién va dirigido?" en un encabezado de segundo nivel (Encabezado 2).

Este apartado identificará de manera clara y específica los diferentes grupos para los que el activo es relevante, describiendo sus necesidades y cómo el activo les proporciona valor.

• Identifica claramente el público objetivo principal del activo. Sé específico sobre los roles, las habilidades o los tipos de proyectos para los que el activo es relevante.
• Amplía el público objetivo si existen grupos secundarios o casos de uso adicionales.
• Describe las necesidades que el activo ayuda a resolver para ese público. ¿Qué problemas específicos aborda el activo para sus usuarios?
• Menciona los beneficios específicos que cada grupo del público objetivo puede obtener del activo. Adapta los beneficios a las necesidades de cada grupo.

Beneficios

Se incluirá a continuación del apartado "¿A quién va dirigido?" en el campo Contenido y se utilizará un encabezado de segundo nivel (Encabezado 2) para el título del apartado.

• Enfócate en los resultados y el valor para el desarrollador: Describe qué mejoras o ventajas concretas experimentarán los desarrolladores o los proyectos al utilizar el activo.
• Utiliza un lenguaje positivo y orientado a los beneficios.
• Sé conciso. Evita explicaciones largas; cada punto debe ser una ventaja clara.
• Utiliza un formato de lista (viñetas) para facilitar la lectura y la identificación de los beneficios.

Detalles técnicos

Se incluirá a continuación del apartado "Beneficios" en el campo Contenido y se utilizará un encabezado de segundo nivel (Encabezado 2) para el título del apartado.

El apartado proporcionará una lista concisa y específica de las principales tecnologías, arquitecturas, librerías y estándares utilizados en el activo, con una breve descripción de su función o versión cuando sea relevante. Su objetivo es ofrecer una visión rápida de la infraestructura técnica del activo. Para ello, puedes utilizar una lista con viñetas.

Repositorios de código

Se incluirá a continuación del apartado "Detalles técnicos" en el campo Contenido y se utilizará un encabezado de segundo nivel (Encabezado 2) para el título del apartado.

En este apartado se referenciará cómo acceder al código del framework y otros artefactos del mismo.

Hoja de ruta

Se incluirá a continuación del apartado "Repositorios de código" en el campo Contenido y se utilizará un encabezado de segundo nivel (Encabezado 2) para el título del apartado.

Contendrá los principales hitos previstos para la evolución del framework, precisando, si es posible, fechas en las que se espera la publicación de próximas versiones.

Contendrá el resumen en formato tabla, con las columnas y filas similares al ejemplo siguiente:

A continuación, se precisará el detalle de cada versión, con un título tipo Encabezado 3 y una breve descripción de las novedades de la versión.

Versionado

Para crear las versiones, se ha de utilizar el tipo de contenido "Versión":

• Consulta la forma de crear versiones y asociarlas al recurso, tanto para normas como para otros recursos.
• Y las pautas de redacción del tipo de contenido Versión.

La ficha del framework:

• Tiene que estar asociado a sus diferentes versiones.

Las versiones del framework incluirán enlaces al código y notas de versión.