Consider splitting `add` or adding flag for truly manual transactions

[ohbadiah]

Despite the Starbucks example in the documentation, issues #13 and #16 indicate some confusion about the intended purposes of match and add. Here's what I've teased out:

• match is meant to complement import and update. Accounts chosen during match should be deterministic so that:
  1. The classifier can consistently choose the right account for everything, making the process mostly a rubber-stamp.
  2. The import ledger effectively reproduces the record from the real accounts transactions are being imported from.
• add is used to create transactions offsetting those from the import:
  1. By entering the amount, the desired source transaction can be automatically selected.
  2. Once a destination account is chosen and the newly entered transaction is finished, the source transaction is marked so it doesn't come up in a subsequent add.
• But add is also used to manually enter transactions that will not appear on any bank or credit account statement. Cash transactions are the most notable example. No one is tracking them but oneself, so there's no electronic record to pull them from. But they constitute a nontrivial part of one's finances.

Both of these uses of add are similar in that they won't match a bank statement and they are ad-hoc and per-transaction, but they are nontrivially different as well. The second use is for real transactions, not just for bookkeeping and classification purposes, and should never offset imported transactions.

At the least, the documentation of this process and these distinctions could be improved. But perhaps these two senses of add should be split into two separate subtly-different commands. The second sense seems to me to reflect the word add better; the first sense might be called offset or whatever the accounting term for this process is called. If two separate commands aren't called for, perhaps a flag to add could distinguish between them.

[johannesgerer]

Thanks for taking the time to write this pretty accurate summary.

I agree that the name 'add' is not helpful, I basically adopted it from the 'add' command that is there in hledger, when I started the project and did not know what I was doing.

However, I would not make that strong of a distinction between the two use cases. Both of them are real, and you might add one of the first kind before importing it.

Are you suggesting that the difference between 'offset' and 'manual enter' should only be that the manual one does not suggest and offer to prefill your transaction with the values of an imported one? Are you saying it is confusing/inefficient to get these suggestions if all you want to do is add a manual one?

The accounting term for both kinds is 'to book something' or to enter a transaction and in accounting terms there is no real difference between the two either, although the first kind involves some kind of so called 'reconciliation'.

What about rename 'add' with 'book', 'enter', or 'manual' and than a flag '--no-suggestions' or '-n' for short?

On November 30, 2017 11:07:19 PM GMT+00:00, Nicholas McAvoy notifications@github.com wrote:

Despite the Starbucks example in the documentation, issues #13 and #16 indicate some confusion about the intended purposes of match and add. Here's what I've teased out:

• match is meant to complement import and update. Accounts chosen during match should be deterministic so that:
  1. The classifier can consistently choose the right account for everything, making the process mostly a rubber-stamp.
  2. The import ledger effectively reproduces the record from the real accounts transactions are being imported from.
• add is used to create transactions offsetting those from the import:
  1. By entering the amount, the desired source transaction can be automatically selected.
  2. Once a destination account is chosen and the newly entered transaction is finished, the source transaction is marked so it doesn't come up in a subsequent add.
• But add is used to manually enter transactions that will not appear on any bank or credit account statement. Cash transactions are the most notable example. No one is tracking them but oneself, so there's no electronic record to pull them from. But they constitute a nontrivial part of one's finances.

Both of these uses of add are similar in that they won't match a bank statement and they are ad-hoc and per-transaction, but they are nontrivially different as well. The second use is for real transactions, not just for bookkeeping and classification purposes, and should never offset imported transactions.

At the least, the documentation of this process and these distinctions could be improved. But perhaps these two senses of add should be split into two separate subtly-different commands. The second sense seems to me to reflect the word add better; the first sense might be called offset or whatever the accounting term for this process is called. If two separate commands aren't called for, perhaps a flag to add could distinguish between them.

-- You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub: https://github.com/johannesgerer/buchhaltung/issues/24

[johannesgerer]

What's your opinion on my proposal?

[ohbadiah]

Sorry, I'm in the midst of a move and haven't been able to really sit down with this. I like renaming add to book; I like the idea of using the real accounting term.

Based solely on existing functionality I think a flag to disable suggestions is sufficient. However, I also intend to propose additional functionality for the booking process, such as passing an hledger filter as a command-line argument and working through a group of transactions. I can imagine these two use cases diverging such that a simple flag would not be sufficient. But splitting the commands could wait for such time as it's warranted.