Towards Prioritizing Documentation Effort

@article{McBurney2018TowardsPD,
  title={Towards Prioritizing Documentation Effort},
  author={Paul W. McBurney and Siyuan Jiang and Marouane Kessentini and Nicholas A. Kraft and Ameer Armaly and Mohamed Wiem Mkaouer and Collin McMillan},
  journal={IEEE Transactions on Software Engineering},
  year={2018},
  volume={44},
  pages={897-913}
}
Programmers need documentation to comprehend software, but they often lack the time to write it. Thus, programmers must prioritize their documentation effort to ensure that sections of code important to program comprehension are thoroughly explained. In this paper, we explore the possibility of automatically prioritizing documentation effort. We performed two user studies to evaluate the effectiveness of static source code attributes and textual analysis of source code towards prioritizing… 

Figures and Tables from this paper

Interactive Refactoring Documentation Bot
TLDR
A semi-automated refactoring documentation bot that helps developers to interactively check and validate the documentation of the refactorings and/or quality improvements at the file level for each opened pull-request before being reviewed or merged to the master.
A Refactoring Documentation Bot
TLDR
A semi-automated refactoring documentation bot that helps developers to interactively check and validate the documentation of the refactorings and/or quality improvements at the file level for each opened pull-request before being reviewed or merged to the master.
Assessing the alignment between the information needs of developers and the documentation of programming languages: A case study on Rust
TLDR
This paper presents an automated approach to support documenters in evaluating the differences and similarities between the concrete information need of developers and the current state of documentation (a problem that is referred to as the topical alignment of a programming language documentation).
Prioritizing documentation effort: Can we do better?
TLDR
An unsupervised approach based on PageRank to prioritize documentation effort that does not need any training data to build the prediction model and is superior to the state-of-the-art ANN approach in prioritizing important modules for documentation effort.
Refactorings Recommendation via Commit Message Analysis
TLDR
This study provides compelling evidence of the value of using the information contained in existing commit messages to recommend future refactorings, and outperform prior studies that apply refactoring based on static and dynamic analysis of code alone.
Improving access to API documentation for developers with Docs‐as‐Code‐as‐a‐service
TLDR
Dev Center is presented, a system based in part on the Docs‐as‐Code framework and designed to provide ubiquitous access to a broad set of API documentation resources that could potentially improve API comprehension and developer productivity.
Is This Class Thread-Safe? Inferring Documentation using Graph-Based Learning
  • Andrew Habib, Michael Pradel
  • Computer Science
    2018 33rd IEEE/ACM International Conference on Automated Software Engineering (ASE)
  • 2018
TLDR
The key idea is to combine a lightweight static analysis that extracts a graph representation from classes with a graph-based classifier, enabling the approach to infer thread safety documentation with high confidence.
Toward the Automatic Classification of Self-Affirmed Refactoring
...
1
2
...

References

SHOWING 1-10 OF 80 REFERENCES
Automatic documentation generation via source code summarization of method context
TLDR
This paper proposes a technique that includes this context by analyzing how the Java methods are invoked, and finds that programmers benefit from the generated documentation because it includes context information.
Improving automated source code summarization via an eye-tracking study of programmers
TLDR
An eye-tracking study of 10 professional Java programmers in which the programmers read Java methods and wrote English summaries of those methods is presented and the findings are applied to build a novel summarization tool.
The relevance of software documentation, tools and technologies: a survey
This paper highlights the results of a survey of software professionals. One of the goals of this survey was to uncover the perceived relevance (or lack thereof) of software documentation, and the
Towards automatically generating summary comments for Java methods
TLDR
A novel technique to automatically generate descriptive summary comments for Java methods is presented, given the signature and body of a method, which identifies the content for the summary and generates natural language text that summarizes the method's overall actions.
Automatic generation of natural language summaries for Java classes
TLDR
This paper presents a technique to automatically generate human readable summaries for Java classes, assuming no documentation exists, and determines that they are readable and understandable, they do not include extraneous information, and, in most cases, they are not missing essential information.
Automatic Source Code Summarization of Context for Java Methods
TLDR
A source code summarization technique that writes English descriptions of Java methods by analyzing how those methods are invoked is proposed and found that while it does not reach the quality of human-written summaries, it does improve over the state-of-the-art summarization tool in several dimensions by a statistically-significant margin.
How software engineers use documentation: the state of the practice
TLDR
The results confirm the widely held belief that SEs typically do not update documentation as timely or completely as software process personnel and managers advocate, however, the results also reveal that out-of-date software documentation remains useful in many circumstances.
Predicting source code changes by mining change history
TLDR
An approach that applies data mining techniques to determine change patterns can be used to recommend potentially relevant source code to a developer performing a modification task and can reveal valuable dependencies by applying to the Eclipse and Mozilla open source projects.
To Document or Not to Document? An Exploratory Study on Developers' Motivation to Document Code
TLDR
The motivating aspects of code documenting the authors find include improving code comprehensibility, order, and quality and the hindering aspects include developers’ perception of documenting as a tedious, difficult, and time consuming task that interrupts the coding process.
How do professional developers comprehend software?
TLDR
An observational study of 28 professional developers from seven companies, investigating how developers comprehend software finds that developers put themselves in the role of end users by inspecting user interfaces and that face-to-face communication is preferred to documentation.
...
1
2
3
4
5
...