This document summarizes a study on developers' motivation to document code. Through interviews and surveys, researchers identified hindering and motivating factors for code documentation. Hindering factors included documentation being tedious, difficult, time-consuming, and interrupting coding work. Motivating factors included documentation improving code comprehensibility, order, and quality. The researchers propose designing a solution to encourage documentation by emphasizing motivating factors and mitigating hindering ones. They plan to further validate findings through a quantitative questionnaire. The goal is to increase developers' internal motivation to document code.

1. 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 P A R T M E N T , U N I V E R S I T Y O F
H A I F A , 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 P A R T M E N T , U N I V E R S I T Y O F H A I F A , I S R A E L
H A Y I M M A K A B E E
P O N T I S , I S R A E L

2. 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.

3. Software Architecture Lab. 3
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)

4. Software Architecture Lab. 4
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).

5. Software Architecture Lab. 5
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?

6. Software Architecture Lab. 6
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?

7. Software Architecture Lab. 7
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

8. Software Architecture Lab. 8
Findings
Hindering
vs.
Motivating
aspects of documentation

9. Software Architecture Lab. 9
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."

10. Software Architecture Lab. 10
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."

11. Software Architecture Lab. 11
Additional findings
 No formal company policy
 All participants reported that their company does not have a
formal policy regarding documentation
 Being 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

12. Software Architecture Lab. 12
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.

13. Software Architecture Lab. 13
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

14. Software Architecture Lab. 14
The next step
 Distribute a quantitative questionnaire for
further refinement, validation and
generalization of our findings.

15. Software Architecture Lab. 15
Brief description of the questionnaire
 Practices vs. beliefs
 Company and peer feedback
 State of mind during coding vs. documenting
 Background questions

16. Software Architecture Lab. 16
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________________

17. Software Architecture Lab. 17
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.

18. Software Architecture Lab. 18
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 tasks
3. 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 documenting
9. 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 it
12. 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

19. Software Architecture Lab. 19
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.

20. Software Architecture Lab. 20
Thank you for your attention!