DOI:
https://doi.org/10.14483/22487638.24849Published:
2026-06-01Issue:
Vol. 30 No. 88 (2026): Abril - JunioSection:
ResearchMetrics for the evaluation of documentation format in agile software projects
Métricas para la evaluación del formato de la documentación en proyectos de software ágil
Keywords:
Documentation Debt, Metrics, Agile software development, Technical Debt, Software Quality (en).Keywords:
Deuda de la Documentación, Métricas, Desarrollo Ágil de Software, Deuda Técnica, Calidad de Software (es).Downloads
Abstract (en)
Objective: This paper proposes a metrics model for assessing and making documentation debt visible in agile software development, with a specific focus on the Format dimension. Methodology: Based on a systematic literature review, the study identified critical risks and applied the Goal-Question-Metric (GQM) paradigm to design indicators. Both subjective metrics, based on perception, and objective metrics, based on structural analysis, were defined to evaluate attributes such as readability, conciseness, and clarity.
Results: A five-dimensional architecture was defined (Structure, Format, Usability, Correlation, and Auditability) and specific metrics were developed for the Format dimension, addressing readability, conciseness, and clarity. These metrics integrate subjective user evaluation with objective structural complexity indicators—such as Average Words per Sentence (PPO)—to quantify risks associated with code misunderstanding and communication failures.
Conclusions: Format deficiencies can give rise to serious risks, including communication failures. The combined use of subjective and objective metrics is essential for a holistic diagnosis, transforming documentation quality into a measurable engineering attribute that can be managed proactively.
Abstract (es)
Objetivo: este trabajo propone un modelo de métricas para evaluar y visibilizar la deuda de la documentación en el desarrollo ágil de software, enfocándose específicamente en la dimensión de Formato.
Metodología: a partir de una revisión sistemática de literatura, se identificaron riesgos críticos y se aplicó el paradigma Goal-Question- Metric (GQM) para diseñar indicadores. Se definieron métricas subjetivas (basadas en percepción) y objetivas (análisis estructural) para evaluar atributos como legibilidad, concisión y claridad.
Resultados: se definió una arquitectura de cinco dimensiones (Estructura, Formato, Usabilidad, Correlación y Auditabilidad) y se desarrollaron métricas específicas para el Formato, abordando la Legibilidad, Concisión y Claridad. Estas métricas integran la evaluación subjetiva del usuario con indicadores objetivos de complejidad estructural, como el Promedio de Palabras por Oración (PPO), para cuantificar riesgos asociados a la incomprensión del código y fallas de comunicación.
Conclusiones: las deficiencias de formato son causantes de riesgos graves como fallas de comunicación. La sinergia entre métricas subjetivas y objetivas es indispensable para un diagnóstico holístico, transformando la calidad documental en un atributo de ingeniería medible para su gestión proactiva.
References
[1] E. Aghajani et al., "Software documentation issues unveiled," in Proc. IEEE/ACM Int. Conf. Softw. Eng. (ICSE), Montreal, QC, Canada, 2019, pp. 1199–1210. https://doi.org/10.1109/ICSE.2019.00122
[2] G. Matturro, F. Raschetti, and C. Fontán, "A systematic mapping study on soft skills in software engineering," J. Univers. Comput. Sci., vol. 25, no. 1, pp. 16–41, 2019. https://doi.org/10.3217/jucs-025-01-0016
[3] N. Rios, R. O. Spínola, M. Mendonça, and C. Seaman, "The practitioners' point of view on the concept of technical debt and its causes and consequences: A design for a global family of industrial surveys and its first results from Brazil," Empir. Softw. Eng., vol. 25, no. 5, pp. 3216–3287, 2020. https://doi.org/10.1007/s10664-020-09832-9
[4] S. Al-Saqqa, S. Sawalha, and H. Abdelnabi, "Agile software development: Methodologies and trends," Int. J. Interact. Mobile Technol., vol. 14, no. 11, pp. 246–270, 2020. https://doi.org/10.3991/ijim.v14i11.13269
[5] M. Fowler, "Technical debt quadrant," Oct. 2009. Accessed: Oct. 17, 2022. [Online]. Available: https://martinfowler.com/bliki/TechnicalDebtQuadrant.html
[6] A. Martini, T. Besker, and J. Bosch, "Process debt: A first exploration," in Proc. Asia-Pacific Softw. Eng. Conf. (APSEC), Singapore, 2020, pp. 316–325. https://doi.org/10.1109/APSEC51365.2020.00040
[7] J. P. Zumba and C. A. L. Arreaga, "Evolución de las metodologías y modelos utilizados en el desarrollo de software," INNOVA Res. J., vol. 3, no. 10, pp. 20–33, Oct. 2018. https://doi.org/10.33890/innova.v3.n10.2018.65
[8] N. Rios et al., "Hearing the voice of software practitioners on causes, effects, and practices to deal with documentation debt," in Lecture Notes in Computer Science, vol. 12130. Cham, Switzerland: Springer, 2020, pp. 55–70. https://doi.org/10.1007/978-3-030-44429-7_4
[9] Y. Shmerlin, I. Hadar, D. Kliger, and H. Makabee, "To document or not to document? An exploratory study on developers' motivation to document code," in Lecture Notes in Business Information Processing, vol. 215. Cham, Switzerland: Springer, 2015, pp. 100–106. https://doi.org/10.1007/978-3-319-19243-7_10
[10] A. A. H. Alzahrani, "Software systems documentation: A systematic review," Int. J. Adv. Comput. Sci. Appl., vol. 15, no. 8, 2024. https://doi.org/10.14569/IJACSA.2024.0150816
[11] D. V. Koznov, D. V. Luciv, and G. A. Chernishev, "Duplicate management in software documentation maintenance," CEUR Workshop Proc., vol. 1989, pp. 195–201, 2017.
[12] J. Zhi, V. Garousi-Yusifoglu, B. Sun, G. Garousi, S. Shahnewaz, and G. Ruhe, "Cost, benefits and quality of software development documentation: A systematic mapping," J. Syst. Softw., vol. 99, pp. 175–198, 2015. https://doi.org/10.1016/j.jss.2014.09.042
[13] J. Bayer and D. Muthig, "A view-based approach for improving software documentation practices," in Proc. Int. Symp. Workshop Eng. Comput. Based Syst. (ECBS), Potsdam, Germany, 2006, pp. 269–278. https://doi.org/10.1109/ECBS.2006.18
[14] M. Zanoni, F. Perin, F. A. Fontana, and G. Viscusi, "Pattern detection for conceptual schema recovery in data-intensive systems," J. Softw.: Evol. Process, vol. 26, no. 12, pp. 1172–1192, 2014. https://doi.org/10.1002/smr.1656
[15] J. D. Arthur and K. T. Stevens, "Assessing the adequacy of documentation through document quality indicators," in Proc. Conf. Softw. Maintenance (ICSM), Miami, FL, USA, 1989, pp. 40–49. https://doi.org/10.1109/icsm.1989.65192
[16] R. Plosch, A. Dautovic, and M. Saft, "The value of software documentation quality," in Proc. Int. Conf. Quality Softw. (QSIC), Dallas, TX, USA, 2014, pp. 333–342. https://doi.org/10.1109/QSIC.2014.22
[17] M. Kajko-Mattsson, "A survey of documentation practice within corrective maintenance," Empir. Softw. Eng., vol. 10, no. 1, pp. 31–55, 2004. https://doi.org/10.1023/B:LIDA.0000048322.42751.ca
[18] A. Forward and T. C. Lethbridge, "The relevance of software documentation, tools and technologies: A survey," in Proc. 2002 ACM Symp. Document Eng., McLean, VA, USA: ACM, 2002, pp. 26–33. https://doi.org/10.1145/585058.585065
[19] N. Qamar, N. Sabahat, and A. Mosavi, "Evaluating the impact of pair documentation on requirements quality in agile software development," IEEE Access, vol. 13, pp. 45784–45794, 2025. https://doi.org/10.1109/ACCESS.2025.3550123
[20] J.-C. Narváez-Narváez, C.-J. Pardo-Calvache, and C.-E. Orozco-Garcés, "Deuda de la documentación en el desarrollo ágil de software: mapeo sistemático de la literatura," Rev. Cient., vol. 46, no. 1, pp. 107–121, Jan. 2023. https://doi.org/10.14483/23448350.19670
[21] V. R. Basili and G. Caldiera, "The goal question metric paradigm," in Encyclopedia of Software Engineering, J. J. Marciniak, Ed. New York, NY, USA: Wiley, 1994, vol. 2, pp. 528–532. [Online]. Available: https://go.umd.edu/3ol7AtO
[22] R. Flesch, "A new readability yardstick," J. Appl. Psychol., vol. 32, no. 3, pp. 221–233, 1948. https://doi.org/10.1037/h0057532
How to Cite
APA
ACM
ACS
ABNT
Chicago
Harvard
IEEE
MLA
Turabian
Vancouver
Download Citation
License
Copyright (c) 2026 Juan Carlos Narváez, César Jesús Pardo Calvache
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
Esta licencia permite a otros remezclar, adaptar y desarrollar su trabajo incluso con fines comerciales, siempre que le den crédito y concedan licencias para sus nuevas creaciones bajo los mismos términos. Esta licencia a menudo se compara con las licencias de software libre y de código abierto “copyleft”. Todos los trabajos nuevos basados en el tuyo tendrán la misma licencia, por lo que cualquier derivado también permitirá el uso comercial. Esta es la licencia utilizada por Wikipedia y se recomienda para materiales que se beneficiarían al incorporar contenido de Wikipedia y proyectos con licencias similares.
