The document discusses the concept of documentation debt in software development, highlighting its causes, such as the undervaluation of comments by developers and the misconception that good code is self-explanatory. It outlines research goals to understand developers' reluctance to document code and proposes utilizing persuasive technology to increase documentation compliance. The planned studies include think-aloud sessions and experiments to evaluate the effectiveness of a documentation-triggering tool.

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.