doi: 10.56294/gr202439

EDITORIAL

Guidelines for writing software building reports

Pautas para la redacción de informes de creación de softwares

Annier Jesús Fajardo Quesada¹ *, René Herrero Pacheco¹ *

¹Universidad de Ciencias Médicas de Granma. Facultad de Ciencias Médicas de Bayamo. Granma, Cuba.

Citar como: Fajardo Quesada AJ, Herrero Pacheco R. Guidelines for writing software building reports. Gamification and Augmented Reality. 2024; 2:39. https://doi.org/10.56294/gr202439

Enviado: 22-10-2023                   Revisado: 04-02-2024                   Aceptado: 23-04-2024                 Publicado: 24-04-2024

Editor: Adrián Alejandro Vitón Castillo

ABSTRACT

The linkage of software with various areas of knowledge has increased significantly, highlighting the importance of process automation thanks to the expansion of imaginative capabilities in this area. The concept of software now encompasses applications on different operating systems, including PWAs, websites, command line applications and APIs. This landscape demands standardized methods for the creation and dissemination of applications, although there is currently no detailed guidance for writing reports on software creation. It is crucial to adopt methodological guidelines that allow the reproducibility of software research, clearly differentiating between the creation and the evaluation-validation of these tools. Such differentiation helps to avoid confusion and ensures consistency in reporting, especially when the objective is to develop new tools. Before starting software development, it is essential to consider the objective, scope and existence of similar technologies, assessing the real need to create a new solution. The article proposes a detailed outline for writing software development reports, covering from the introduction, method, results, to the discussion and conclusions. This outline covers aspects such as the theoretical and historical framework, the importance and necessity of the product, classification of the study, details of the creation process, technologies used, and software evaluation. It highlights the importance of performing quality tests throughout the development, ensuring that the final results reflect the most recent and conclusive state of the software. The creation of software is presented as a non-linear process that requires iterations and adaptations based on functionality and quality tests, whose results directly influence the progress of the project. The suggested model is flexible, allowing adjustments according to the specific characteristics of the software under development.

Keywords: Process Automation; Software Development; Research Methodologies; Development Reports.

RESUMEN

La vinculación de software con diversas áreas del conocimiento ha aumentado significativamente, destacando la importancia de la automatización de procesos gracias a la expansión de las capacidades imaginativas en este ámbito. El concepto de software ahora engloba aplicaciones en distintos sistemas operativos, incluyendo PWA, sitios web, aplicaciones de línea de comando y APIs. Este panorama demanda métodos estandarizados para la creación y divulgación de aplicaciones, aunque actualmente no existe una guía detallada para la redacción de informes sobre la creación de software. Es crucial adoptar pautas metodológicas que permitan la reproducibilidad de la investigación en software, diferenciando claramente entre la creación y la evaluación-validación de estas herramientas. Dicha diferenciación ayuda a evitar confusiones y garantiza la coherencia en los informes, especialmente cuando el objetivo es desarrollar nuevos instrumentos. Antes de comenzar con el desarrollo de software, es esencial considerar el objetivo, alcance y la existencia de tecnologías similares, evaluando la necesidad real de crear una nueva solución. El artículo propone un esquema detallado para la redacción de informes de creación de software, cubriendo desde la introducción, método, resultados, hasta la discusión y conclusiones. Este esquema abarca aspectos como el marco teórico e histórico, la importancia y necesidad del producto, clasificación del estudio, detalles del proceso de creación, tecnologías utilizadas, y evaluación del software. Resalta la importancia de realizar pruebas de calidad a lo largo del desarrollo, asegurando que los resultados finales reflejen el estado más reciente y concluyente del software. La creación de software se presenta como un proceso no lineal que requiere iteraciones y adaptaciones basadas en pruebas de funcionalidad y calidad, cuyos resultados influyen directamente en el avance del proyecto. El modelo sugerido es flexible, permitiendo ajustes según las características específicas del software en desarrollo.

Palabras clave: Automatización de Procesos; Creación de Software; Metodologías de Investigación; Informes de Desarrollo.

En los últimos años la vinculación de los softwares con todas las áreas del conocimiento ha crecido vertiginosamente. El hecho de que la imaginación sea el límite de los procesos que se puedan automatizar ha incrementado el número de investigaciones de softwares, y especialmente, investigaciones dedicadas a la creación de los mismos. Software en la actualidad abarca a toda aplicación independientemente del sistema operativo objetivo, ya sea instalable o portable, y se incluyen las PWA (progressive web applications) y los sitios web, así como las aplicaciones para la línea de comando y las APIs (Application Programming Interfaces).

Hay diversos métodos que estandarizan una vía óptima para la creación de aplicaciones,⁽²⁾ tanto de manera general como específica al campo o tipo de aplicación, pero la ciencia no se detiene en la creación, el paso siguiente es la divulgación, y para esto se utilizan los informes escritos y uno de los tipos más populares es el formato de articulo científico. En la actualidad no hay ninguna guía detallada para redactar informes de creación de software.

La investigación sin método es ciencia caótica, que no se puede reproducir, por lo que es necesario establecer pautas metodológicas para estas investigaciones, adaptarlas al formato publicable para su posterior divulgación.

Para los informes de investigaciones de softwares siempre es recomendable separar los de creación de los de evaluación-validación pues cada uno es de por si un entorno de investigación independiente, enlazados por el mismo producto, pero con técnicas diferentes. Esto no quiere decir que en el informe del proceso de creación no se haga alusión a resultados de las pruebas que se van haciendo para determinar la calidad de algunas funcionalidades.

Un informe cuyo objetivo fue crear un nuevo instrumento necesita nuevas especificidades pues su método coincide con los resultados por lo que puede dar lugar a confusión y redacción incoherente o redundante.

Previo iniciar la creación de todo software y su posterior informe se debe tener en cuenta el objetivo y alcance del mismo, luego de una previa investigación de si existen tecnologías similares para no crear duplicados, así como si es verdaderamente necesario crear un software y no un formato leíble por otra tecnología, por ejemplo, un sitio o aplicación web sobre un tema en particular para estudiantes de una universidad cuando se puede dar la misma información en un power point interactivo y distribuirlo por las redes sociales.

Un esquema que se puede seguir para la redacción de informes de creación de softwares es el siguiente:

Introducción

· Marco teórico: Conceptos principales

· Marco histórico: ¿Cómo era antes de la app para realizar las tareas que automatiza o ejecuta la misma?

· Importancia del producto: ¿Qué problema resuelve?

· Necesidad del producto. ¿Es único en el ‘mundo’?, de no ser así, ¿en qué supera a sus similares (viabilidad, costo, eficiencia, diseño, etc.)?

· Objetivo

Método

· Clasificación del estudio

- Suelen ser estudios de innovación tecnológicas

· Datos generales del proceso de creación

- Lugar en el que se creó el software

- Tamaño del equipo de trabajo y experiencia de sus integrantes

- Tiempo que demoró la creación del mismo

- Otros datos de interés       

· Método de desarrollo de software en caso de haberse utilizado alguno

· Lenguajes de programación

· Módulos o paquetes de los lenguajes y el objetivo de cada uno

· Herramientas y tecnologías

- FrontEnd o diseño de la UI (User Interface).

- Bases de datos

- Almacenamiento

- Vinculación con APIs

- Otras

· Sistema en el que se montó

- Sistema operativo y kernel y sus versiones (si procede)

- Memoria

- Procesador

· Método para recolectar la información (en el caso de productos que necesiten mostrar información o bases de datos, entre otros) Procede como en los artículos de revisión

- Bases de datos y buscadores

- Términos de búsqueda

- Filtros

- Métodos de análisis de la información

· Método de evaluación del software

· Declaración de principios éticos de ser necesario

Resultados

· Describir UI

- Mostrar imágenes de la app funcional, Ventanas representativas

· Describir UX (User Experience)

- Que utilidades se agregaron para mejorar la experiencia de usuario, ej. Tooltips, Shortkeys, etc.

· Describir requerimientos finales, dependencias necesarias

- Hardware

- Sistema Operativo

- Aplicaciones

· Resultados en la última evaluación de prueba

- Velocidad

- Interfaz Grafica

- Eficacia

- Accesibilidad

Discusión

· A partir de los resultados hacer un contraste con otros estudios de aplicaciones similares o con la documentación oficial de dichas aplicaciones resaltando en que supera y en que es superado.

Conclusiones

· Puntos fuertes y limitaciones

· Proyecciones y alcance esperado

Tener en cuenta que la creación de un software o aplicación no es un proceso lineal y se deben hacer pruebas de calidad o funcionabilidad que pueden determinar el avance o regresión del proceso. Los últimos resultados que se obtienen de la misma son los que deben plasmarse en el informe por resultar los concluyentes en la fase de creación. Estas pruebas no son definitivas pues para eso existen estudios de validación en otros entornos y son la verdadera demostración de alcance de la app.

Según el tipo de software algunos de los puntos presentados en este modelo pueden extenderse o simplificarse, pues algunos son solo de contenido visual, otros con elementos puramente analíticos o incluso la combinación de ambos. También es válido agregar otros datos según sea pertinente ya que se trata de un modelo flexible.

REFERENCIAS BIBLIOGRÁFICAS

1.    Carrizo D, Alfaro A, Carrizo D, Alfaro A. Método de aseguramiento de la calidad en una metodología de desarrollo de software: un enfoque práctico. Ingeniare Rev Chil Ing [Internet]. 2018 [citado 6 de febrero de 2024];26(1):114-29. Disponible en: http://dx.doi.org/10.4067/S0718-33052018000100114

FINANCIACIÓN

Ninguna.

CONFLICTO DE INTERESES

Ninguno.

CONTRIBUCIÓN DE AUTORÍA

Conceptualización: Annier Jesús Fajardo Quesada.

Investigación: Annier Jesús Fajardo Quesada, René Herrero Pacheco.

Visualización: Annier Jesús Fajardo Quesada.

Redacción – borrador original: Annier Jesús Fajardo Quesada, René Herrero Pacheco.

Redacción – revisión y edición: Annier Jesús Fajardo Quesada, René Herrero Pacheco.