Computing Reviews
Today's Issue Hot Topics Search Browse Recommended My Account Log In
Review Help
Search
Necessary and neglected?: An empirical study of internal documentation in agile software development teams
Stettina C., Heijstek W.  SIGDOC 2011 (Proc. of the 29th ACM International Conference on Design of Communication, Pisa, Italy, Oct 3-5, 2011)159-166.2011.Type:Proceedings
Date Reviewed: Feb 3 2012

Agile programming is not known for favoring internal software documentation. Since internal documentation does not directly contribute to making clients happy, agile programmers exhibit little enthusiasm for drafting ideas in plain text.

Stettina and Heijstek address two research questions: “How do team members in agile software development projects document their work?” “How do they perceive the amount and importance of their internal documentation?” The paper provides the results of a study on agile software engineering teams. They surveyed the software documentation habits of 79 professionals in 13 different countries. One of their main findings is that “documentation alone is insufficient.” On the one hand, the amount of internal documentation is generally perceived as too little. On the other hand, documenting software is seen as a burden on programmers.

This well-written and easy-to-read paper highlights an important paradox within the agile movement: internal documentation is recognized as essential, but very few actually write it. I am personally involved in many open-source projects. Indeed, not much documentation is written in plain text; however, we dedicate a great deal of time to writing unit tests and interacting with our clients.

One thing that is missing from the paper is a clear definition of “documentation.” I find unit tests and code examples useful as plain descriptions; should these not be regarded as part of the documentation?

All in all, this excellent paper is accessible to a very large audience. No particular background is required to properly grasp the content.

Reviewer:  Alexandre Bergel Review #: CR139814 (1207-0707)
Bookmark and Share
  Reviewer Selected
Featured Reviewer
 
 
Methodologies (D.2.1 ... )
 
 
Documentation (D.2.7 ... )
 
 
Distribution, Maintenance, and Enhancement (D.2.7 )
 
 
Project And People Management (K.6.1 )
 
Would you recommend this review?
yes
no
Other reviews under "Methodologies": Date
Multilevel specification of real time systems
Gabrielian A., Franklin M. Communications of the ACM 34(5): 50-60, 1991. Type: Article
May 1 1992
Software requirements
Davis A., Prentice-Hall, Inc., Upper Saddle River, NJ, 1993. Type: Book (9780138057633)
Nov 1 1994
The automated production control documentation system
Trammell C., Binder L., Snyder C. ACM Transactions on Software Engineering and Methodology 1(1): 81-94, 1992. Type: Article
Mar 1 1993
more...

E-Mail This Printer-Friendly
Send Your Comments
Contact Us
Reproduction in whole or in part without permission is prohibited.   Copyright 1999-2024 ThinkLoud, Inc.®
Terms of Use
| Privacy Policy