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.
Large-scale Logging Made Easy: Meetup at Deutsche Bank 2024
To document or not to document? An exploratory study on developers' 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
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.