Evaluating the Quality of the Documentation of Open Source Software

Lerina Aversano, Daniela Guardabascio, Maria Tortorella

Abstract

Software documentation is a basic component of the software development process: from the definition of the functional requirements to the maintenance phase. Software documentation refers to different types of documents that facilitates the software developer’s tasks. Then, it includes the textual documentation required by the Software engineering standards, API documentation, Wiki pages and source code comments. Surveys and studies indicate that the documentation is not always available and, if available, only partially addresses the developers' needs, as it is often wrong, incomplete, out-of-date and ambiguous. This paper focuses on the quality assessment of the documentation of open source systems with the aim of understanding the support it can offer for adopting them and executing maintenance activities. Specifically, a quality model is defined and a preliminary investigation of its applicability is performed.

References

  1. Arthur, J.D., Stevens, K. T., 1989, Assessing the adequacy of documentation through document quality indicators. Conference on Software Maintenance, IEEE comp. soc. press, pp. 40-49.
  2. Briand, L. C., 2003. Software documentation: how much is enough? Software Maintenance and Reengineering, Seventh European Conference. IEEE comp. soc. press., pp. 13-15.
  3. Chomas, V. S., Saini, J. R., 2015, Software Template for Evaluating and Scoring Software Project Documentations. Int. Journal of Computer Applications, 116(1).
  4. Cozzetti de Souza, S., Anquetil, N., de Oliveira, K.M., 2005. A Study of the Documentation Essential to Software Maintenance. 23rd Annual Int. Conference on Design of communication: documenting & designing for pervasive (SIGDOC 7805), ACM press, pp.68-75.
  5. Cutts, M., 2013. Oxford guide to plain English. OUP Oxford.
  6. Dautovic A., Plösch, R., Saft, M., 2011. Automated quality defect detection in software development documents. First Int. Workshop on Model-Driven Software Migration (MDSM 2011).
  7. Diaz-Pace, J.A., Nicoletti, M., Schettino, S., Grisando, R., 2014. A recommender system for technical software documentation in Wikis. Biennial Congress of Argentina (ARGENCON), IEEE comp. soc. press, pp. 393-398.
  8. Garousi, G., Garousi, V., Moussavi, M., Ruhe G., Smith, B., 2013. Evaluating usage and quality of technical software documentation: an empirical study. 17th Int. Conference on Evaluation and Assessment in Software Engineering (EASE). ACM, pp. 24-35.
  9. Flesch, R., 2016. How to Write Plain English. University of Canterbury.
  10. Forward, A., Lethbridge, T. C., 2002. The relevance of software documentation, tools and technologies: a survey. Symposium on Document engineering, ACM press, pp. 26-33.
  11. Kipyegen, N. J., Korir, W. P. K., 2013. Importance of Software Documentation. IJCSI Int. Journal of Computer Science, 10(5), pp.1694-0784
  12. IEEE Std 830-1998. 1998. IEEE Recommended Practice for Software Requirements Specifications.
  13. IEEE Std 1028-2008. 2008. IEEE Standard for Software Reviews and Audits.
  14. IEEE Std 1063-2001. 2001. IEEE Standard for Software User Documentation.
  15. ISO/IEC 9126:2001. 2001. Software engineering - Product quality.
  16. ISO/IEC 25010:2005. 2005. Software engineering - Software product Quality Requirements and Evaluation (SquaRE).
  17. ISO/IEC 26514:2008. 2008. Systems and software engineering - Requirements for designers and developers of user documentation.
  18. Lethbridge, T. C., Singer, J., Forward, A., 2003. How software engineers use documentation: The state of the practice. IEEE Software, 20(6), pp. 35-39.
  19. Plösch, R., Dautovic, A., Saft, M., 2014, The Value of Software Documentation Quality. 14th Int. Conference on Quality Software. IEEE comp. soc. press, pp. 333- 342.
  20. Satzinger, J. W., Jackson, R. B., Burd, S. D., 2000. System Analysis and Design in a Changing World , Thomson Learning.
  21. Sommerville I, 2005. Software Documentation. Software Engineering, Volume 2: The Supporting Process, pp. 143-154.
  22. Uddin, G., Robillard, M. P., 2015. How API documentation fails. IEEE Software, 32(4), pp. 68-75.
  23. Wingkvist, A., Ericsson, M., Lucke, R., Lowe, W., 2010. A metrics-based approach to technical documentation quality. 7th Int. Conference on the Quality of Information and Communications Technology (QUATIC). IEEE comp. soc. press, pp. 476-481.
Download


Paper Citation


in Harvard Style

Aversano L., Guardabascio D. and Tortorella M. (2017). Evaluating the Quality of the Documentation of Open Source Software . In Proceedings of the 12th International Conference on Evaluation of Novel Approaches to Software Engineering - Volume 1: ENASE, ISBN 978-989-758-250-9, pages 308-313. DOI: 10.5220/0006369403080313


in Bibtex Style

@conference{enase17,
author={Lerina Aversano and Daniela Guardabascio and Maria Tortorella},
title={Evaluating the Quality of the Documentation of Open Source Software},
booktitle={Proceedings of the 12th International Conference on Evaluation of Novel Approaches to Software Engineering - Volume 1: ENASE,},
year={2017},
pages={308-313},
publisher={SciTePress},
organization={INSTICC},
doi={10.5220/0006369403080313},
isbn={978-989-758-250-9},
}


in EndNote Style

TY - CONF
JO - Proceedings of the 12th International Conference on Evaluation of Novel Approaches to Software Engineering - Volume 1: ENASE,
TI - Evaluating the Quality of the Documentation of Open Source Software
SN - 978-989-758-250-9
AU - Aversano L.
AU - Guardabascio D.
AU - Tortorella M.
PY - 2017
SP - 308
EP - 313
DO - 10.5220/0006369403080313