Usage and usefulness of technical software documentation: An industrial case study

Garousi, Golara; Garousi-Yusifoğlu, Vahid; Ruhe, Guenther; Zhi, Junji; Moussavi, Mahmoud; Smith, Brian T.

doi:10.1016/j.infsof.2014.08.003

Cited by 48 publications

(25 citation statements)

References 34 publications

Supporting

Mentioning

Contrasting

Order By: Relevance

“…In turn, the negative examples indicate that a paper does not employ a particular statistical technique. For example, Garousi et al [30] write in their validity threats section that "Furthermore, we have not conducted an effect size analysis on the data and results; thus this is another potential threat to the conclusion validity." We take this as a strong indication that there is no use of effect size calculations in their analysis.…”

Section: Overall Design Of Review Toolmentioning

confidence: 99%

“…Explicit (without evidence). "The aforementioned results are valuable to practitioners, because they provide indications for testing and refactoring prioritization" [1] or "The proposed approach can be utilized and applied to other software development companies" [30]. Even though the first statement might seem a bit more explicit compared to the second statement, neither has a clear connection to the output from statistical analysis.…”

Section: Practical Significancementioning

confidence: 99%

See 1 more Smart Citation

Evolution of statistical analysis in empirical software engineering research: Current state and steps forward

Neto

Torkar

Feldt

et al. 2019

Journal of Systems and Software

View full text Add to dashboard Cite

Software engineering research is evolving and papers are increasingly based on empirical data from a multitude of sources, using statistical tests to determine if and to what degree empirical evidence supports their hypotheses. This is not only crucial for research progress but also for practitioners in judging the practical significance. To investigate the practices and trends of statistical analysis in empirical software engineering (ESE), this paper presents a review of a large pool of papers from top-ranked software engineering journals. First, we manually reviewed 161 papers producing a review protocol based on a view of the recent state of art concerning statistical analysis and how researchers discuss practical significance. In a second phase of our method, we used the protocol as ground truth for a more extensive semi-automatic classification of papers spanning the years 2001-2015 targeting a total of 5,196 papers.We use the results from both review processes to: i) identify and analyse the predominant practices in ESE (e.g., using t-test or ANOVA), as well as relevant trends in usage of specific statistical methods (e.g., nonparametric tests and effect size measures); and ii) create a conceptual model for a statistical analysis workflow with suggestions on how to apply different statistical methods as well as guidelines to avoid pitfalls with their use, such as the arbitrary α cut-off and neglecting to correct for multiple tests. Additionally, we discuss different techniques to further expand the statistical toolkit of ESE researchers: Bayesian data analysis, techniques to handle missing data, and causal analysis.Lastly, we confirm existing claims that current ESE practices lack a standard to report practical significance of results. We illustrate how practical significance can be discussed in terms of both the statistical analysis and in the practitioner's context. 1 Even though the approaches mentioned cover Software Engineering (SE) as a whole, this paper focuses on the broad branch of all SE that is mainly interested in empirical data, i.e. Empirical Software Engineering (ESE).2 Even though the common approach of judging statistical significance by the use of p-values have recently come under severe scrutiny [96] we here talk about statistical significance in a broader sense of the word.

show abstract

Section: Overall Design Of Review Toolmentioning

confidence: 99%

Section: Practical Significancementioning

confidence: 99%

Evolution of statistical analysis in empirical software engineering research: Current state and steps forward

Neto

Torkar

Feldt

et al. 2019

Journal of Systems and Software

View full text Add to dashboard Cite

show abstract

“…Even less work is published that quantifies both the costs and benefits, or the return on investment of using software documentation. One notable example is the work by Garousi et al in [54], where a cost-effectiveness index of technical software documents is calculated by dividing the number of times that a document is accessed or downloaded (benefit) by the time spent editing this document (cost).…”

Section: Cost-benefit Analysismentioning

confidence: 99%

How organisation of architecture documentation affects architectural knowledge retrieval

Graaf¹,

Liang

Tang

et al. 2016

Science of Computer Programming

View full text Add to dashboard Cite

A common approach to software architecture documentation in industry projects is the use of file-based documents. This approach offers a single-dimensional arrangement of the architectural knowledge. Knowledge retrieval from file-based architecture documentation is efficient if the organisation of knowledge supports the needs of the readers; otherwise it can be difficult. In this paper, we compare the organisation and retrieval of architectural knowledge in a file-based documentation approach and an ontologybased documentation approach. The ontology-based approach offers a multi-dimensional organisation of architectural knowledge by means of a software ontology and semantic wiki, whereas file-based documentation typically uses hierarchical organisation by directory structure and table of content. We conducted case studies in two companies to study the efficiency and effectiveness of retrieving architectural knowledge from the different organisations of knowledge. We found that the use of better knowledge organisation correlates with the efficiency and effectiveness of AK retrieval. Professionals who used the knowledge organisation found this beneficial.

show abstract

“…Due to space limit, we restrict our focus to recent industrial studies covering aspects that overlap with the scope of this work. The work of Garousi et al [5] explored how technical documentation is used and what factors impact its usefulness in practice. Plösch et al [7] assessed the most important quality attribute of software documentation via a survey.…”

Section: Related Workmentioning

confidence: 99%

“…Unlike previous studies and surveys that have been conducted in this field (e.g. [5,3,7]), this work has a special focus on how documents are searched for. Furthermore, previous studies usually focused on the use of technical software documentation by software engineers, while this work considers all documents that are produced and used by practitioners holding various technical and non-technical positions.…”

Section: Introductionmentioning

confidence: 99%

An Exploratory Study on Managing and Searching for Documents in Software Engineering Environments

Charrada

Mussato²

2016

Proceedings of the 2016 ACM Symposium on Document Engineering

View full text Add to dashboard Cite

A large number of documents are usually produced in the software industry. In this work, we conduct a qualitative study to explore the main practices and challenges related to managing these documents. The results of this study are based on interviews with 13 practitioners from nine companies. The main findings of the study are: (1) much data is stored in e-mails and in meeting protocols, (2) practitioners like wikis, (3) when searching for documents, practitioners would rather browse the structure than use the search function and (4) searching for documents is still a challenge due to the low effectiveness of search functions and the scattering of documents over several locations and tools.

show abstract

Usage and usefulness of technical software documentation: An industrial case study

Cited by 48 publications

References 34 publications

Evolution of statistical analysis in empirical software engineering research: Current state and steps forward

Evolution of statistical analysis in empirical software engineering research: Current state and steps forward

How organisation of architecture documentation affects architectural knowledge retrieval

An Exploratory Study on Managing and Searching for Documents in Software Engineering Environments

Contact Info

Product

Resources

About