Creating and evolving developer documentation: understanding the decisions of open source contributors

@inproceedings{Dagenais2010CreatingAE,
  title={Creating and evolving developer documentation: understanding the decisions of open source contributors},
  author={Barth{\'e}l{\'e}my Dagenais and Martin P. Robillard},
  booktitle={FSE '10},
  year={2010}
}
Developer documentation helps developers learn frameworks and libraries. To better understand how documentation in open source projects is created and maintained, we performed a qualitative study in which we interviewed core contributors who wrote developer documentation and developers who read documentation. In addition, we studied the evolution of 19 documents by analyzing more than 1500 document revisions. We identified the decisions that contributors make, the factors influencing these… 
View on ACM
ics.uci.edu
103 Citations
Highly Influential Citations
12
Background Citations
60
Methods Citations
10
Results Citations
1

Figures and Tables from this paper

103 Citations

Citation Type

Citation Type

Analysis and Recommendations for Developer Learning Resources
TLDR
This thesis is that by studying how the relationships between documentation, code, and users’ support needs are created and maintained, it can identify documentation improvements and automatically recommend some of these improvements to contributors.
Using Traceability Links to Recommend Adaptive Changes for Documentation Evolution
TLDR
AdDoc is proposed, a technique that automatically discovers documentation patterns, i.e., coherent sets of code elements that are documented together, and that reports violations of these patterns as the code and the documentation evolves.
Software Documentation Issues Unveiled
TLDR
A large scale empirical study, where 878 documentation-related artifacts stemming from four different sources are mined, analyzed, and categorized, resulting in a detailed taxonomy of documentation issues from which a series of actionable proposals both for researchers and practitioners are inferred.
Extracting Development Tasks to Navigate Software Documentation
TLDR
TaskNavigator is presented, a user interface for search queries that suggests tasks extracted from software documentation in an auto-complete list along with concepts, code elements, and section headers, to help developers navigate documentation.
Documentation practices in scientific software development
  • Aleksandra Pawlik, J. Segal, M. Petre
  • Computer Science, Education
    2012 5th International Workshop on Co-operative and Human Aspects of Software Engineering (CHASE)
  • 2012
TLDR
The role of users' community in scientific software documentation is explored and the findings are compared to studies about documentation practices of professional software developers and how production of documentation in scientificSoftware development can be supported.
When Not to Comment: Questions and Tradeoffs with API Documentation for C++ Projects
TLDR
A set of questions maintainers and tool developers should consider when improving API-level documentation is identified, which may provide only limited value for developers, while requiring effort maintainers don't want to invest.
Application Programming Interface Documentation: What Do Software Developers Want?
TLDR
The results show that developers initially try to form a global understanding regarding the overall purpose and main features of an API, but then adopt either a concepts-oriented or a code-oriented learning strategy that API documentation both needs to address.
Documentation Reuse: Hot or Not? An Empirical Study
TLDR
This paper performs an empirical study of duplications in JavaDoc documentation on a corpus of seven famous Java APIs and makes a proposal for a simple but efficient automatic reuse mechanism.
An Empirical Study on Evolution of API Documentation
TLDR
Based on the methodology, a quantitative study on API documentation evolution of five widely used real-world libraries is conducted, and the results reveal various valuable findings that allow programmers and library developers to better understandAPI documentation evolution.
Creating a shared understanding of testing culture on a social coding site
TLDR
Several strategies that software developers and managers can use to positively influence the testing behavior in their projects are found, however, project owners on GitHub may not be aware of them.
...
1
2
3
4
5
...

References

SHOWING 1-10 OF 26 REFERENCES
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…
Pedagogical framework documentation: how to document object-oriented frameworks. an empirical study
TLDR
It is found that different documentation styles are better for different situations, depending on what your goals are, and guidelines that can help someone who is trying to document a framework are discovered.
An empirical study of software developers' management of dependencies and changes
  • C. D. Souza, D. Redmiles
  • Business, Sociology
    2008 ACM/IEEE 30th International Conference on Software Engineering
  • 2008
TLDR
The concept of impact management is proposed as an analytical framework to present software developers' strategies to handle the effect of software dependencies and changes in their work and is used to suggest avenues for future research in change impact analysis techniques.
What programmers really want: results of a needs assessment for SDK documentation
TLDR
This paper steps the reader through a needs assessment of programmers that was conducted by instructional designers to identify what learning support programmers need and want to successfully use a new software development kit (SDK).
Automatically locating framework extension examples
TLDR
This work devised an approach that uses the framework documentation as a template and that finds instances of this template in a code base given lightweight documentation of a framework based on the experience with concern-oriented documentation.
Moving into a new software project landscape
TLDR
It is theorized that there are three primary factors that impact the integration experience of newcomers: early experimentation, internalizing structures and cultures, and progress validation.
What Makes APIs Hard to Learn? Answers from Developers
TLDR
The article focuses on the obstacles to learning an API and concludes that as APIs keep growing larger, developers will need to learn a proportionally smaller fraction of the whole.
Identifying and addressing problems in object-oriented framework reuse
TLDR
A long-term empirical investigation into object-oriented framework reuse concludes that, although a combination of pattern language and micro-architecture documentation is useful for framework reuse, the forms of these documentation types require further enhancement to become effective.
Improving API documentation usability with knowledge pushing
  • Uri Dekel, J. Herbsleb
  • Computer Science
    2009 IEEE 31st International Conference on Software Engineering
  • 2009
TLDR
This work presents a lab study that demonstrates the directive awareness problem in traditional documentation use and the potential benefits of an Eclipse plug-in named eMoose, which decorates method invocations whose targets have associated directives.
A reuse case perspective on documenting frameworks
TLDR
The concept of a reuse case is proposed as offering a perspective of the different approaches to documenting frameworks, and the categories of reuse cases are defined.
...
1
2
3
...