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

ABSTRACT

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 decisions and the consequences for the project. Among many findings, we observed how working on the documentation could improve the code quality and how constant interaction with the projects' community positively impacted the documentation.

References

1. S. Adolph, W. Hall, and P. Kruchten. A methodological leg to stand on: lessons learned using grounded theory to study software development. In Proc. Conf. of the Center for Advanced Studies on Collaborative Research, pages 166--178, 2008.
2. G. Butler, P. Grogono, and F. Khendek. A reuse case perspective on documenting frameworks. In Proc. IEEE Asia Pacific Soft. Eng. Conf., pages 94--101, 1998.
3. J. M. Carroll, P. L. Smith-Kerker, J. R. Ford, and S. A. Mazur-Rimetz. The minimal manual. Journal of Human-Computer Interaction, 3(2):123--153, 1987.
4. I. Chai. Framework Documentation: How to document object-oriented frameworks. An empirical study. PhD in Computer Sscience, University of Illinois at Urbana-Champaign, 2000.
5. J. Corbin and A. C. Strauss. Basics of Qualitative Research: Techniques and Procedures for Developing Grounded Theory. Sage Publications, 3rd edition, 2007.
6. J. W. Creswell. Qualitative Inquiry and Research Design. Sage Publications, 2nd edition, 2007.
7. B. Dagenais and H. Ossher. Automatically locating framework extension examples. In Proc. ACM SIGSOFT Intl Symposium on Foundations of Soft. Eng., pages 203--213, 2008.
8. B. Dagenais, H. Ossher, R. K. Bellamy, M. P. Robillard, and J. P. de Vries. Moving into a new software project landscape. In Proc. IEEE/ACM SIGSOFT Intl Conf. on Soft. Eng., pages 275--284, 2010.
9. C. R. B. de Souza and D. F. Redmiles. An empirical study of software developers' management of dependencies and changes. In Proc. Intl Conf. on Soft. Eng., pages 241--250, 2008.
10. U. Dekel and J. D. Herbsleb. Improving api documentation usability with knowledge pushing. In Proc. IEEE/ACM SIGSOFT Intl Conf. on Soft. Eng., pages 320--330, 2009.
11. A. Forward and T. C. Lethbridge. The relevance of software documentation, tools and technologies: a survey. In Proc. ACM Symposium on Document Engineering, pages 26--33, 2002.
12. D. Kirk, M. Roper, and M. Wood. Identifying and addressing problems in object-oriented framework reuse. Journal of Empirical Soft. Eng., 12(3):243--274, 2007.
13. J. Nykaza, R. Messinger, F. Boehme, C. L. Norman, M. Mace, and M. Gordon. What programmers really want: results of a needs assessment for sdk documentation. In Proc. Intl Conf. on Computer Documentation, pages 133--141, 2002.
14. M. P. Robillard. What makes apis hard to learn? answers from developers. IEEE Software, 26(6):27--34, 2009.
15. M. B. Rosson, J. M. Carrol, and R. K. Bellamy. Smalltalk scaffolding: a case study of minimalist instruction. In Proc. ACM SIGCHI Conf. on Human Factors in Computing Systems, pages 423--430, 1990.
16. T. Schäfer, I. Aracic, M. Merz, M. Mezini, and K. Ostermann. Clustering for generating framework top-level views. In Proc. Working Conf. on Reverse Eng., pages 239--248, 2007.
17. S. Thummalapenta and T. Xie. SpotWeb: Detecting framework hotspots and coldspots via mining open source code on the web. In Proc. IEEE/ACM Intl Conf. on Automated Soft. Eng., pages 327--336, 2008.
18. H. Zhong, T. Xie, L. Zhang, J. Pei, and H. Mei. MAPO: Mining and recommending API usage patterns. In Proc. European Conf. on Object-Oriented Programming, pages 318--343, 2009.

Index Terms

• Software and its engineering

  • Software creation and management

    • Software post-development issues

      • Documentation