To document or not to document? An exploratory study on developers' motivation to document code

Software Architecture Lab.

To document or not to document?

An exploratory study on developers' motivation to document code

Y U L I A S H M E R L I N , I R I T H A D A R

I N F O R M A T I O N S Y S T E M S D E PA R T M E N T, U N I V E R S I T Y O F H A I FA , I S R A E L

D O R O N K L I G E R E C O N O M I C S D E PA R T M E N T, U N I V E R S I T Y O F H A I FA , I S R A E L

H A Y I M M A K A B E EP O N T I S , I S R A E L

Software Architecture Lab. 2

Documentation debt

Technical debt The situation in a project when developers accept

compromises in one dimension of a system in order to meet urgent demands in other dimensions (Clear, 2003 )

Includes code-related and non-code related elements

Documentation debt A component of technical debt (Tom, 2013)

The situation in which software products lack the necessary internal documentation.


The importance of documentation

Developers are often aware of the importance of documentation (Tenny, 1988)

However -Code documentation is often overlooked in

practice (Fluri, 2007)


Reasons for the lack of documentation

External – stemming from the work environment Example: strict deadlines urge developers to focus

on executable code, often leaving the documentation behind.

Internal – inherent in the developers themselves Example: documenting is not perceived a creative

activity developers prefer solving algorithmic problems over writing documentation (Clear, 2003).


Related works

Software developers' motivation has been researched. For example: The job characteristics model (Couger et al., 1980) The model of task design (Gambill et al., 2000).

These models examine the motivation for the software development profession as a whole

Motivation model for code documentation?


Research goal and question

We aim to explore and better understand developers' motivation for code documenting.

Research question: What are the motivating and the hindering aspects that influence developers’ code documenting behavior?


Research settings

Data collection and analysis are performed using qualitative – and subsequently quantitative – research methods.

The research consists of three stages:1. Five in-depth interviews 2. Distribution of pilot questionnaire among

ten additional participants.

3. Large-scaled distribution of refined questionnaire


Findings

Hinderingvs.

Motivatingaspects of documentation


Categories of hindering aspects of documentation

Documentation is a…tedious task

“…to explain what each parameter does.”

difficult task “Sometimes I do not know how to explain the change.”

interruption of coding “Documenting breaks the continuity of coding.”

time consuming "When I have a tight deadline, documenting is left behind."


Categories of motivating aspects of documentation

Documentation promotes…code comprehensibility

“Documentation makes the code more readable and easier to understand later on, for me and for other people that look at the code.”

order “It helps to keep things in order.”

overall code quality "Good documentation shows that your work

was done perfectly."


Additional findings

No formal company policy All participants reported that their company does not

have a formal policy regarding documentationBeing forced to document by company

policy would not be an effective solution "Most of the developers are creative people and do

not like to be told how to do their job.” These results further emphasize the need to

focus on internal motivation of developers in order to encourage them to document


Conclusions

Developers' reluctance to document is related to their negative perception of the task of documenting. Documenting is perceived as tedious,

difficult, time consuming and distracting from the main task of coding.

Most of the developers could also find motivating aspects. Documentation increases quality and

understandability of code.


The vision: A conceptual solution

In order to increase developers' motivation to document, a proposed solution for encouraging documentation should: emphasize the motivating aspects mitigate the hindering aspects


The next step

Distribute a quantitative questionnaire for further refinement, validation and generalization of our findings.


Brief description of the questionnaire

Practices vs. beliefs Company and peer feedbackState of mind during coding vs.

documentingBackground questions


Example question 1:

When do you think is the preferable time to document: before developing a segment of code after developing a method after developing a class at the end of the workday rarely or never other________________

When do you usually document: before developing a segment of code after developing a method after developing a class at the end of the workday rarely or never other________________


Example question 2:

Do you normally receive positive feedback regarding documentation from your peers or managers? (You may choose more than one answer).

Normally I do not receive positive feedback on my documentation

Normally people say my documentation is good. Normally people say my documentation is sufficient. Normally people say my documentation helps them.


Example question 3:

The following statements refer to the way in which you have experienced code documentation work during the last two weeks.Please indicate how often you experienced the state of mind described in each of the statements. (1 = never, 2 = almost never, 3 = sometimes, 4 = regularly, 5 = often, 6 = very often, 7 = always).1. When I am documenting, I think about nothing else 2. I get carried away by my documentation tasks3. When I am documenting, I forget everything else around me 4. I am totally immersed in my documentation tasks 5. My documentation tasks give me a good feeling 6. I do my documentation tasks with a lot of enjoyment 7. I feel happy during documentation 8. I feel cheerful when I am documenting9. I would still do documentation tasks, even if I received less pay 10. I find that I also want to document in my free time 11. I document because I enjoy it12. When I am working on documentation tasks, I am doing it for myself 13. I get my motivation from the documentation challenge itself, and not from the monetary reward for it


The next steps

Distribute a quantitative questionnaire for further refinement, validation and generalization of our findings.

Designing a solution based on these findings for increasing developers' motivation to document their code.


Thank you for your attention!