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.