Why do developers struggle with documentation while excelling at programming

Abstract

In software engineering, technical documentation is one of the activities that play an important role for the success of software projects. When developing software systems a lot of time is spent not only implementing your own solutions into the code but also understanding and maintaining the code solution produced by others. However with an emerging agile community the priority and engagement in documentation may stagnate and effort invested into those activities may to some extent be considered inherently wasteful. Therefore, the current perception for many software engineers may be that technical documentation is incomplete and not updated. An important aspect of the issue of producing documentation is the motivation of the developers who are responsible for its completion. A question that might be asked is if documentation overall is an activity that the software community would be better off without, or if it is a neglected activity with room for improvement. For that reason this exploratory multiple case study aims to identify some of the issues to shed some light on why technical documentation has got into such an unfavourable position in the software industry. The study investigate the motivation affecting software engineers when producing software documentation, how this motivation evolves over time and why there is a difference compared to other activities in the software industry. The study consider prospect theory as an explanatory theory for how improvements in outcomes are perceived in terms of value. In addition this study also analyses how experiences are remembered and evaluated, as it relates to how excitement is considered for similar tasks in the future. The study can affirm that software engineers’ motivation seems to be affected by excitement and value dimensions when it comes to producing technical documentation. Additionally, in the long term, receiving constructive feedback can improve the excitement and the perceived value of writing technical documentation. The study finally observes that developers to a higher extent seem intrinsically motivated by the coding activity than the documentation activity, which the study points out as a primary enabler for the difference in behaviour between the coding and documentation activity.