Base Documentation on Program Sample File

[flywire]

PP comes with sample files for user testing and it would be useful if the use could also test the documentation file.

Options:

1. Use an existing sample file
2. Modify and use and existing sample file
3. Add documentation file to program samples

[hug-sch]

There could be much improvement in my currently used example files. When I began working on the docs, I reviewed both existing sample files, but encountered some issues. The DAX sample file is heavily focused on Germany, featuring only purchase transactions and one deposit, all from 2018. The Kommer file is more recent and includes more types of transactions, but they are all related to ETFs. I'm struggling with the decision between using a sample file that is easy to comprehend and useful for demonstrating various concepts (such as in my recent chapter on stock splits) and one that provides real-world context. Initially, I was also hesitant to utilize an existing company's data, hence the placeholders like "share-1" and "broker-A."

Also, for the sake of maintenance, such as updating screenshots, it would be preferable to consistently use the same small set of sample files. Maybe, we should decide and agree upon which one (or two/three) we should use. Any suggestions? It’s a good idea to add them to the program samples.

[buchen]

First, I agree that the DAX sample is outdated. We should deleted. I created it back then to demo an industry classification and it was easiest to create this for the DAX.

About the Sommer sample file. I made some changes this week: I added a couple more dividend statements, I added a Bitcoin holding, and I fixed some translations problems.

But I am thinking:

• We should rename it to "demo" or "sample" and remove the "kommer". It was meant as an example for an asset allocation and rebalancing. The sample still can contain this, but should not be limited to this.
• Just as I added Bitcoin, we can add Amazon for an example of a stock split.

The sample is part of the repository as XML: https://github.com/portfolio-performance/portfolio/blob/master/name.abuchen.portfolio.ui/src/name/abuchen/portfolio/ui/parts/kommer.xml

The translation works likes this:

• First, placeholders in the form if ${Kommer_BrokerageAccount} are replaced with the translation
• Second, all dashboard widgets get the original translated name
• Third, the taxonomies for industry classification, regions, etc. get the original translated name
• Fourth, the category identifier of the taxonomy are re-generated with unique IDs. That is necessary, because in the original file the identifier might be "DE" for "Germany" but it can show up in multiple taxonomies. I need it unique to identify data series.

Personally, I update the sample like this:

• Open the file from the repository
• Add the securities, transactions, whatever
• In the commit editor, pick only the relevant changes (for example, I do not want all historical prices in the file)
• Add the translation labels

My gut feeling is: unless we have a complex different example, I would rather enhance the existing demo file.

[hug-sch]

From a documentation perspective, I would recommend the following modifications to the kommer.xml file:

• Rename the file to demo-portfolio.xml or sample-portfolio.xml. The longer name seems preferable as "demo" or "sample.xml" is perhaps too generic.
• Include deposit accounts in other currencies, such as USD and GBP (or GBX), to address conversion issues.
• Incorporate individual securities like Amazon (USD, useful for demonstrating splits), NN Group (EUR (Netherlands), for explaining dividend choices), Rio Tinto (GBP/GBX or USD/AUD), Daimler Truck Holding, and Mercedes-Benz Group (illustrative of spin-offs), and NVIDIA (popular choice). For the individual securities, should we try to cover a representative sample of sectors and countries/continents (Asia, Africa)?
• Introduce bonds; I used Volkswagen, but perhaps one with longer duration is better for maintenance.
• Other assets, such as gold? Bitcoin has been introduced lately.
• Each transaction type (buy, sell, delivery, dividend, etc.) should be represented by at least one transaction. Haven't found yet a suitable example to illustrate the delivery transaction.
• Investment plan (but have not researched it yet).

[flywire]

I don't think demo, implying a fully contained example, is the right term. I particularly like the ability to use a sample file and either save it with a new name or regenerate fresh test data. A sample file can still be used for demonstrations in the manual and forum.

[hug-sch]

Yes, you're right. sample.xml or sample-portfolio.xml better suits the content and it can be used in the manual.

Do you have any suggestions regarding the content?

[flywire]

I like the suggestions above but data will be required for other functionality. Start there and expand/consolidate data as required.

[hug-sch]

The text Reconstruct sample-portfolio.md contains the beginning of a proposal for the extension and updating of the kommer.xml file.

Any corrections and suggestions are welcome.

[Sn1kk3r5]

@buchen

My gut feeling is: unless we have a complex different example, I would rather enhance the existing demo file.

Are you fine, if I try to add to following stuff?

• 2 more Cash Accounts, USD and GB
• Amazon Stock in USD
• NN Group (choice Dividend)
• Rio Tinto (GBP/GBX)
• Daimler Truck Holding
• Mercedes-Benz Group (illustrative of spin-offs)
• NVIDIA (popular choice)

In case I'am able to perform this, I would then create the corresponding bookings. If it's fine for you.
Cheers

[hug-sch]

@buchen Hi Andreas,

@Sn1kk3r5 has finished the updating of the kommer.xml. As already discussed above, it seems better to rename the file; for example sample.xml or demo.xml. Is that OK with you?

[flywire]

RE portfolio-performance/portfolio#4022 & 7fa0b70 There is no account transfer. Instead of a deposit into Foreign Currency Accounts GBP could it be established with a transfer of 200EUR from the Deposit Account?

[Sn1kk3r5]

@flywire

I'll take a note and will bring it with the next PR. For the time being a manual booking should do it :-)
Highest attention was the alignment between English and German in order to make capturing screenshots way easier.

Cheers