Creating and Evolving Developer Documentation
Reviewed by Jorge Aranda / 2011-08-23
Keywords: Documentation
Dagenais2010 Barthélémy Dagenais and Martin P. Robillard: "Creating and evolving developer documentation". Proceedings of the eighteenth ACM SIGSOFT international symposium on Foundations of software engineering - FSE '10, 10.1145/1882291.1882312.
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.
Contributors to a new open source software that are beginning to work on its documentation have plenty of choices available to them. For instance, they could put their efforts in a public wiki, or set a separate documentation team, or just deal with documentation piecemeal, as questions for the use of their software arise in a forum. These decisions have significant consequences for the project later on. Dagenais and Robillard's paper is a good description of these important decisions and their consequences. I don't think many seasoned open source developers will find most results surprising (which is good for this kind of paper!), but they'll appreciate having them collected and validated empirically.
Table 3 is the best summary of the paper's findings, if you don't have time to read it whole, but it's a bit hard to parse if you haven't at least skimmed through the earlier pages.