Re: hledger documentation ideas - part 3

[Simon Michael]

>> If it would be helpful for you to have me turn the examples into real postings for any or all of the above, just say the word, and I will gladly do so.
>
>
> In tests, examples, and sometimes docs, I often use minimal data, and a few conventions, like:
>
> - ISO YYYY-MM-DD dates
> - first day of the year
> - no description
> - a b c for account names
> - A B C for commodities
> etc.
>
> This is to reduce mental effort of generating them, and to help the reader focus on the thing being explained rather than incidental details. Also to reduce dependence on the english language.
>
> I think that works for people familiar with the syntax, but I agree that sometimes it can look less realistic, more obscure and offputing to people learning, who don't yet have a solid grasp of the parts of a journal entry, or who haven't learned the (unbalanced posting) notation.
>
> I think we'd like to keep all of these benefits, so it's a tradeoff. Also, while the needs are different for developer tests and for user-facing docs and examples, there is some advantage in using a similar style for both, for ease of re-use.
>
> With that in mind, which of these do you think are worth adopting as preferred policy, in user-facing docs at least ?
>
> 1. using 2+ balanced postings, avoiding unnecessary use of (unbalanced postings)
>
> 2. using realistic account names (english or multi-language ?)
>
> 3. using realistic commodity symbols (single-character symbols or three-letter codes ?)
>
> 4. adding realistic transaction descriptions
>
> 5. drawing examples from a canonical, consistent example journal or set of example journals where possible, to increase realism and save work (producing, updating and keeping examples correct is costly)
>
> 6. ... ?

Cc'ing here, in case others have thoughts. I think I lean towards realish but short data in user docs and examples, and minimal data in tests.


>
>
> FYI I did a read-through of the hledger manual today and hope to do some section rearranging/renaming soonish.
>

[niels...@gmail.com]

I, too, lean toward real-appearing, but short, data in the user docs and examples. An example would be something like the following (adapted from the current documentation):

2017-01-16 bought groceries

  assets:checking    $-1

  expenses:food        $1 

Also, I would say to use unbalanced postings in the documentation only when we need to show how they work.

Curious what input others might have!

Rob

[the.so...@gmail.com]

I think it is far better to use something realistic-looking.

Even as a (somewhat) experienced user, I have great difficulty understanding examples with A / B / C as commodity symbols.  The five most-traded commodities in the world (as of 2023) are USD / EUR / JPY / GBP / CNY, in that order.  I would suggest using those for the commodity symbols.

If someone would come up with a list of example types (an ontology, essentially), I'm happy to contribute realistic journal entries for those, if needed, which can be used as a basis for an example journal.  Or else a subset of bc.example can be used.

I personally think a dependence on the English language is fine.  To mitigate the problem of Anglo-centricity, I think it would be enough if people using hledger in other languages can contribute one or two translations of the basic examples just to show how it would work.

~ Pranesh

[niels...@gmail.com]

One other thing occurred to me, regarding the currency, is that if "$" is used as the symbol, it applies to several currencies, not just the USD.

I like your idea of example types. One example that would seem more or less universal would be purchasing food. On the other hand, a credit card transaction wouldn't be. That is, there are countries where credit cards are rarely used. Also, even in countries where they are widely used, there are portions of the population that don't use them.

Anybody have any additional ideas regarding of transactions that would be widely applicable around the world?

Rob