Technical debt is a metaphor for the gap between the current state of a software system and its hypothesized ‘ideal’ state. One of the significant and under-investigated elements of technical debt is documentation debt, which may occur when code is created without supporting internal documentation, such as code comments. Studies have shown that outdated or lacking documentation is a considerable contributor to increased costs of software systems maintenance. The importance of comments is often overlooked by software developers, resulting in a notably slower growth rate of comments compared to the growth rate of code in software projects. This research aims to explore and better understand developers’ reluctance to document code, and accordingly to propose efficient ways of using persuasive technology to encourage programmers to document their code. The results may assist software practitioners and project managers to control and reduce documentation debt.

1. Software Architecture Lab.
Reducing Technical Debt:
Using Persuasive Technology for
Encouraging Software Developers
to Document Code
Y U L I A S H M E R L I N , 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 , Y A H O O ! R E S E A R C H L A B S , H A I F A ,
I S R A E L

2. Software Architecture Lab. 2
Documentation Debt
 Technical debt is a metaphor for the gap
between the current state of a software system
and its hypothesized ‘ideal’ state.
 Documentation debt may occur when code
is created without sufficient supporting internal
documentation, such as code comments.
 The growth rate of comments is smaller than
the growth rate of code in software projects.

3. Software Architecture Lab. 3
Causes of Documentation Debt
 The importance of comments is often
overlooked by software developers.
 Some developers perceive writing internal
documentation as a secondary task, as opposed
to writing the code itself.
 Some development approaches promote the
idea that good code should be self-explanatory,
and thus comments are not always necessary.

4. Software Architecture Lab. 4
Documentation Debt Consequences
 Outdated or lacking documentation increases
the costs of software systems maintenance.
 Previous research shows that 40%- 60% of the
maintenance time is spent on studying the
software prior to modification because of the
lack of appropriate documentation.

5. Software Architecture Lab. 5
Research Goals
 Explore and better understand developers’
reluctance to document code.
 Propose efficient ways using persuasive
technology to encourage programmers to
document their code.

6. Software Architecture Lab. 6
Persuasive Technology
 Persuasive technology is an interactive
computer technology designed with the goal of
reinforcing, changing or shaping people’s
attitudes or behavior.
 Shaping purposes: create a behavior pattern for
a specific situation which did not exist prior to
using the system.

7. Software Architecture Lab. 7
Fogg Behavior Model
 Fogg Behavior Model has three factors:
 Motivation
 Ability
 Triggers
 Behavior activation threshold: For the trigger to
evoke the desired behavior, a person has to be
above that threshold, in high enough level of
motivation and ability.

8. Software Architecture Lab. 8
Research Plan
We plan two studies:
1. A think-aloud protocol for examining
program maintenance tasks performance.
2. A series of experiments to assess triggers for
documentation.

9. Software Architecture Lab. 9
Think-Aloud Sessions
 Each subject will perform a maintenance task,
namely, add functionality, on a code written
and documented by another person.
 We will observe:
 To what extent the subject relies on the code
documentation during this process.
 What are the important features in code comments
that help understand existing code.

10. Software Architecture Lab. 10
Assess Triggers for Documentation
 Goal: Check if the use of a documentation-
triggering tool improves documentation.
 While exploring also the effect of interventions on
the other Fogg factors (motivation and ability).
 Quantitative results: will be calculated using
documentation metrics.
 Qualitative results: we plan to collect
qualitative data via questionnaires.

11. Software Architecture Lab. 11
Planned Experiments
 Pilot experiments with undergraduate students.
 Experiment with software practitioners:
 During a full-day workshop.
 1st stage: participants implement coding task.
 2nd stage: participants extend code written by others.
 Participants are divided into two groups:
 Both groups are aware that their code will be extended by
someone else.
 One group expects that the quality of their documentation
will be judged.

12. Software Architecture Lab. 12
Conclusions
 We intend to:
 Identify the factors affecting documentation.
 Devise means for increasing compliance with
documentation requirements.
 Create a utility, using persuasive technology
principles, for encouraging and motivating
developers to document their code.
 Our results may assist software practitioners to
control and reduce documentation debt.