Improvements to (English) terminology used in the app

[pfalcon]

Something I wanted to bring up for a while (but was shy too, because English is not my native language, nor I'm too familiar with financial terminology specifically). I know that Portfolio Performance started in German, and it's great to see it's being translated to many languages. I'll specifically touch English translation. So, I suspect that some terminology used in English translation might have heritage in German original. At the very least, some of the terms (in the context used in PP) I barely heard in finance-related contexts, while other terms are usually used in that context. A few examples:

• "Absolute performance %" - it seems that in English, "Total return %" is used almost universally
• "Deposits and Removals" - sorry, that's "Deposits and Withdrawals"

So, overall, I'd like to open this ticket to both bring up the issue, and collect feedback from more users, especially native ones (while keeping in mind and tracking distinction UK- vs US-originated terminology, etc.)

[pfalcon]

Other related issue is consistency of terms/descriptions. For example, it's important to know whether figures (amounts, percentages, etc.) are based on "gross" or "net" data (i.e. whether fees/taxes/etc. are accounted for or not). PP is actually pretty good handling that, as many report-like pages have a "Use gross" setting to let user explicitly switch. However, for many parameters, it's still unclear for end user whether gross or net calculation would be used. An example is "Absolute performance %" above.

So, I would like to propose that for any data value (like column/field name, etc.), it was explicitly stated whether it's net or gross. That can be done e.g. in a tooltip.

[Morpheus1w3]

@pfalcon Join the translation team

POEditor.com Join translations Login with your account Start your translation in your language Have fun....

[buchen]

Thanks @pfalcon for bringing this up. The example "Withdrawals" drove your point home. I immediately realized that this is the right English term.

I also like the proposal to bring up significant changes of terms in this issue first. For example, the change to withdrawal will tough hundreds of terms in POEditor. But there is no way to revert the change, no meaningful history of the translation, etc. (Of course, if you find a typo, an improved translation, etc., feel free to use POEditor directly).

Total return

"Absolute performance %" - it seems that in English, "Total return %" is used almost universally

Sounds reasonable.

The PP definition is:

Absolute performance = market value + sell/outbound deliveries + dividends - taxes - fees - initial valuation - buy/inbound deliveries

Looking at the definition of total return for example in Investopedia, then the PP indicator is not including taxes and fees which I think does not contradict the definition (and we can make it clear with improved net/gross labels).

Withdrawals

"Deposits and Removals" --> "Deposits and Withdrawals"

Agree. Is somebody volunteering to create a pull request for this?

net/gross labels

@Morpheus1w3 writes:

I would like to propose that for any data value (like column/field name, etc.), it was explicitly stated whether it's net or gross. That can be done e.g. in a tooltip.

Makes sense. I believe the "infrastructure" should be there. Some columns already have specific tooltips. We should stick the existing naming convention (see screenshot - "description" is used as tooltip, "menu label" is used if one wants to have a longer/better label in the context menu as opposed to the column heading). I am happy to merge commits on this.

Please post more proposals for term changes in this issue

My input

• "buy and sell transactions" --> "purchase and sale transactions"

[pfalcon]

@buchen : Thanks for reply!

Total return

Looking at the definition of total return for example in Investopedia, then the PP indicator is not including taxes and fees which I think does not contradict the definition (and we can make it clear with improved net/gross labels).

Yes, that's important point that total return can also be net/gross. Specific variety used in PP should be described via a tooltip as discussed above, but the point that they're both useful. An end user is of course interested in their net total return. But as we move to comparing different securities independently of circumstances of individual holders, it's gross total return what's important. So, specifying what exactly PP does allows to see what PP misses ;-). In that regard, https://github.com/portfolio-performance/portfolio/issues/3657.

"buy and sell transactions" --> "purchase and sale transactions"

Oh, I guess that's going to far. "Buy" and "sell" seems to be the standard terms used for these operations, most brokers have the operation buttons named like that, so they're very familiar to users.

feel free to use POEditor directly

I for one don't use tools like POEditor and Eclipse when hacking on PP, just my favorite text editor and command line for building. And at the current pace it may take years for me to get to POEditor. So, indeed, this ticket is to raise awareness and try to build momentum so that interested parties can pull together on it.

[pfalcon]

That can be done e.g. in a tooltip.

Another issue I "finally" noticed recently: "Holding period" for a trade isn't really a holding period, it's weighted average holding period of individual transactions in a trade! For me (as someone who does a bit of math every day), noticing that trade's holding period doesn't match that of individual xacts, it was an immediate hypothesis that it might be a weighted average of it, as something which makes most sense from mathematical point of view. But I still left possibility that it might be something different, like simple average. And only checking the source code, I became sure. I totally have no idea how a "mere human" would feel in this situation, the most likely "PP is buggy!!11". I don't want to bring a question how useful it's to show weighted average as (the only) holding period metric, but the fact that it's what being used really should be disclosed on spot (via a tooltip).

[flywire]

"Holding period" for a trade isn't really a holding period, it's weighted average holding period of individual transactions in a trade! ... the fact that it's what being used really should be disclosed

@hug-sch seems reasonable

[pfalcon]

Filing https://github.com/portfolio-performance/portfolio/issues/4195 made me remember "Capital Gains" vs "Realized Capital Gains" situation, specifically in Portfolio -> Calculation (maybe in other reports too). So, the problem is that it's extra mental step to understand that "Capital Gains" actually means unrealized capital gains. There, it can be done my method of logical exclusion (there's "Realized Capital Gains", so the other one must be unrealized), but how many novices without accounting background would make such a mental step at once again? I guess, most novices would rather be confused: "There's Realized Capital Gains, but also Capital Gains. WTF is that, PP must be nuts".

I understand where it comes from - in some other places in PP, e.g. in table column headings it's not practical to spell "realized" or "unrealized", and then there's convention that in such places, "capital gains" means "unrealized capital gains". Then we go one step further and say that's it's PP global convention that "capital gains" means "unrealized capital gains". Well, doesn't help novices (and given complexity of subject matter and PP itself, people stay novices for years with it). So, I propose to undo that last overextended step ("capital gains" means "unrealized capital gains") and for as long as there's enough space, and if realized vs unrealized are contrasted to each other, then spell "realized" or "unrealized" explicitly.

(And when there's not enough space, then as argued in comments above, there should be tooltip spelling out details like realized/unrealized, net/gross, etc.)

[mierin12]

I agree that in the Calculation the "Unrealized" could be added. It is there in the column in Securities view. So it a clarification and an homogenization. I almost added it in the french translation, but didn't as it would be going a bit further away from a translation task. 😄

Two propositions of clarification also :

• regarding the Trades Widget (n° of trades/n° of positive trades/n° of negative trades) and the Profit/Loss Trades widget, I think a clarification that it applies only to closed trades, instead of all trades would be welcomed. Either in the name of the widget or in a tooltip.

• in the Heatmap widgets (monthly and annual), there is an "Ornament" menu to add sum/geometric mean/standard deviation. Does "ornament" really exist in this context ? If not, then maybe simply "Statistics" would be ok.