Find a consistent name for the new "reimbursement" / "settlement" / "transfer" bill type

[zorun]

The new feature in #1290 uses a mix of "reimbursement" and "settlement" terminology. At one point in the development, it was called "transfer".

We should find a good and consistent name and stick to it. Keep in mind that there are two use-cases:

1. "I just gave 20 € to Bob to help cover my past and future expenses, and I am creating a bill to account for that transfer of money"
2. "I want to settle my debt to other members. So I look at the "Settle" page, I make one or more bank transfers of the right amount, and then I use the "Settle" buttons to automatically create the corresponding bills"

Regarding terminology, I'm not a native English speaker, but from what I understand:

• "reimbursement" / "reimburse" : used to cover for expenses after the fact, e.g. if I buy a sandwich in a business trip, my employer will reimburse me. I think this use-case does not really fit Ihatemoney since it's not a shared expense.
• "settlement" / "settle", e.g. "settle a debt". I owe money to somebody, and I give them back the right amount of money to settle this debt. This is definitely use-case 2
• "transfer": give money to somebody, i.e. decrease a debt I have towards this person or increase a debt this person has towards me. This is definitely use-case 1

I would go with "transfer" for the bill type, since this is what is visible when creating a bill, but keep "settlement" everywhere in the "Settle" page. In the statistics page, I'm thinking of adding two new columns "transferred" (total amount of transfers you made to somebody else) and "received" (total amount of transfers other people have made to you).

Any thought? @TomRoussel @almet

[TomRoussel]

It's good to think about keeping our terminology simple and consistent!

I'm also not a native English speaker, so I can't really say if how I interpret the terminology makes sense or not. I interpret reimbursement as paying back what you owe to someone, so to me it sounds like use-case 1, but specifically to cover past expenses. The way you word it here, "transfer" does sound more general semantically, so that might be the better way to go. I'm more convinced of using transfer, as giving someone some money in advance to cover expenses later is a sensible usecase, and reimbursement is a weird way to phrase that.

In any case, I think it makes the most sense to keeping it to only 2 bill types until there is a convincing other use-case. The terminology in the Settle page is pretty clear I think, so I don't see a reason to change that.

I don't think I would use those extra columns in the statistics page, but maybe others will. In general having some more stats is just fun, so I don't see a downside in adding it.

[zorun]

Thanks for the feedback. Yes, I agree with keeping only 2 bill types, and not changing the terminology of the settle page. I only want to make the name of the new bill type consistent.

For statistics, let's move the conversion to #1300

[almet]

Hey, thanks for opening this discussion. "Transfer" seems a bit to generic to me: everything is a transfer of money in this project. Maybe naming it "direct transfer" would be clearer for us?

After some definition reading, it seems we might not want to dig this further: we're trying to name different kind of money transfer, which can go in opposite directions.

Direct transfer might cover both the "advance payment" and "reimbursement" cases. It would be used internally.

Ihatemoney is used in the wild to mark items that are paid by somebody for somebody else. At some point, people might want to reimburse or settle their debts. I believe that's why we should let the "Settle" button.

---

Just a few definitions I gathered

Reimbursement: the act of paying back money to someone who has spent it for you or lost it because of you, or the amount that is paid back:

Examples:
She has received reimbursement for some of her costs.
Employees can apply for reimbursement of travel expenses.

— The Cambridge Dictionary

Settlement: the action of paying money to someone:

Examples
The settlement of his debts took him several months.
I enclose a cheque in settlement of your claim.
UK Her mother made a settlement on her (= made a formal arrangement to give her money) when she started college.

— The Cambridge Dictionary

Where and how the terms are used in the code

$ grin -I '*.html' -i "Reimburse|Settle|Transfer"
./ihatemoney/templates/edit_project.html:
   53 :                 <span class="mb-1">{{ _('Settle plans') }}</span>
   65 :             <p class="mb-1 text-muted">{{ _('Download the list of transactions needed to settle the current bills.') }}</p>
./ihatemoney/templates/layout.html:
   61 :           <li class="nav-item{% if current_view == 'settle_bill' %} active{% endif %}"><a class="nav-link" href="{{ url_for("main.settle_bill") }}">{{ _("Settle") }}</a></li>
./ihatemoney/templates/settle_bills.html:
   12 :         <thead><tr><th>{{ _("Who pays?") }}</th><th>{{ _("To whom?") }}</th><th>{{ _("How much?") }}</th><th>{{ _("Settled?") }}</th></tr></thead>
   20 :                 <span id="settle-bill" class="ml-auto pb-2">
   21 :                     <a href="{{ url_for('.settle', amount = bill.amount, ower_id = bill.ower.id, payer_id = bill.receiver.id) }}" class="btn btn-primary">
   22 :                         {{ ("Settle") }}

$ grin -I '*.py' -i "Reimburse|Settle|Transfer"
./ihatemoney/models.py:
    8 : from debts import settle
   57 :     REIMBURSEMENT = "Reimbursement"
  139 :             if bill.bill_type == BillType.REIMBURSEMENT:
  193 :     def get_transactions_to_settle_bill(self, pretty_output=False):
  194 :         """Return a list of transactions that could be made to settle the bill"""
  213 :         settle_plan = settle(self.balance.items()) or []
  222 :             for ower_id, amount, receiver_id in settle_plan
./ihatemoney/tests/budget_test.py:
  784 :     def test_reimbursement_bill(self):
  792 :         # create a bill to test reimbursement
  813 :         # test reimbursement bill
  818 :                 "what": "reimbursement for rent",
  821 :                 "bill_type": "Reimbursement",
 1246 :     def test_settle_page(self):
 1248 :         response = self.client.get("/raclette/settle_bills")
 1251 :     def test_settle(self):
 1298 :         transactions = project.get_transactions_to_settle_bill()
 1309 :     def test_settle_button(self):
 1356 :         transactions = project.get_transactions_to_settle_bill()
 1362 :                 "/raclette/settle"
 1370 :             temp_transactions = project.get_transactions_to_settle_bill()
 1374 :             # test if theres a new one with bill_type reimbursement
 1376 :             assert bill.bill_type == models.BillType.REIMBURSEMENT
 1379 :     def test_settle_zero(self):
 1424 :         transactions = project.get_transactions_to_settle_bill()
 1426 :         # There should not be any zero-amount transfer after rounding
./ihatemoney/tests/import_test.py:
  341 :                     "bill_type": "Reimbursement",
  393 :                 "bill_type": "Reimbursement",
  406 :                 "bill_type": "Reimbursement",
  441 :             "2017-01-01,refund,Reimbursement,XXX,13.33,tata,1.0,jeanne",
  530 :                 "bill_type": "Reimbursement",
  544 :                 "bill_type": "Reimbursement",
  578 :             "2017-01-01,refund,Reimbursement,13.33,EUR,tata,1.0,jeanne",
./ihatemoney/web.py:
  538 :         export = g.project.get_transactions_to_settle_bill(pretty_output=True)
  846 : @main.route("/<project_id>/settle_bills")
  847 : def settle_bill():
  849 :     bills = g.project.get_transactions_to_settle_bill()
  850 :     return render_template("settle_bills.html", bills=bills, current_view="settle_bill")
  853 : @main.route("/<project_id>/settle/<amount>/<int:ower_id>/<int:payer_id>")
  854 : def settle(amount, ower_id, payer_id):
  861 :         bill_type=BillType.REIMBURSEMENT,
  862 :         what=_("Settlement"),
  869 :     return redirect(url_for(".settle_bill"))

• There is a "settle" button you can click. It will create a reimbursement bill.
• It marks in the interface if it's "settled" and provide a button to do it otherwise

[zorun]

Hey, thanks for opening this discussion. "Transfer" seems a bit to generic to me: everything is a transfer of money in this project.

I disagree somewhat: paying a shared expense is not a transfer of money between members.

Maybe naming it "direct transfer" would be clearer for us?

I like it!

After some definition reading, it seems we might not want to dig this further: we're trying to name different kind of money transfer, which can go in opposite directions.

Direct transfer might cover both the "advance payment" and "reimbursement" cases.

Agreed: here I'm only talking about naming the bill type, that's why I think it should be somewhat generic to allow for these different cases. The current term "reimbursement" is not generic enough.

It would be used internally.

Not only internally: it's shown when you create a bill, you can choose the bill type.

[zorun]

I did an actual user study with a very representative panel of one person (!), here is the result (in French, sorry):

• mots qui viennent spontanément : "remboursement", "avance" (mais d'accord pour dire qu'il faudrait un mot qui englobe les deux)
• mots qui ne conviennent pas : "don", "contribution", "paiement"
• avis sur "transfert" ou "transfert direct" : 👍

Looking at tricount, they also mention "money transfer":

Dépense, rentrée d'argent, transfert d'argent
Vous avez payé ou reçu de l'argent pour le groupe ? Vous avez avancé de l'argent à un ami ? Prenez facilement tout cela en compte !

It's also a classical term for cash transfers through Western Union and similar companies: https://fr.wikipedia.org/wiki/Transfert_d'argent

[almet]

Yay, let's go with "direct transfer" then :-)

(Agreed on the fact that not everything is a transfer, while rethinking about it, heh)

[almet]

Not only internally: it's shown when you create a bill, you can choose the bill type.

You're right, it is also there.

I wonder if the added cost for the UX is worth the benefit. Adding a new bill type should be optional, at least, or hidden in the interface / not part of the default path (maybe). Maybe it's already the case, I don't have the ability to run a local copy to check this out.

[zorun]

While doing some archeology I found that this was discussed extensively in #137 already :)

(not really the terminology, but the needs)